home *** CD-ROM | disk | FTP | other *** search
/ Magnum One / Magnum One (Mid-American Digital) (Disc Manufacturing).iso / d27 / rpgf_pc2.exe / RFREE.DOC < prev    next >
Text File  |  1991-02-28  |  83KB  |  2,396 lines
  1.  
  2. -----------------------------------------------------------------------------
  3. RFREE.DOC -- RPG/free (tm) and RPG/pretty (tm) documentation
  4. -----------------------------------------------------------------------------
  5.  
  6. Version PC2.02    February 28, 1991
  7. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  8.  
  9. by Paul Conte (Copyright 1990, 1991)
  10.  
  11. Please note:    This document can be reproduced for any purpose, as long as 
  12.         the following notice is included on the first page:
  13.  
  14. ***************************************************************************
  15. ***    RPG/free and RPG/pretty are trademarks of Paul Conte.        ***
  16. ***                                    ***
  17. ***    RPG/free and RPG/pretty programs are                 ***
  18. ***    Software copyright 1990, 1991 by Paul Conte.            ***                             ***
  19. ***************************************************************************
  20.  
  21.  
  22.  
  23.               TABLE OF CONTENTS
  24.               -----------------
  25.  
  26. I.  . . . . . . . . . . . . . . . . How to use this document
  27.  
  28. II. . . . . . . . . . . . . . . . . Introduction
  29.  
  30. III.  . . . . . . . . . . . . . . . Installation
  31.  
  32. IV. . . . . . . . . . . . . . . . . Execution
  33.     IV.A. . . . . . . . . . . . . . . .    DOS commands
  34.     IV.B. . . . . . . . . . . . . . . .    Error files
  35.     IV.C. . . . . . . . . . . . . . . .    Return status
  36.     IV.D. . . . . . . . . . . . . . . .    RPG/free options
  37.     IV.E. . . . . . . . . . . . . . . .    RPG/pretty options
  38.  
  39. V.  . . . . . . . . . . . . . . . . What's new in Versions 2.0 and 2.02
  40.  
  41. VI. . . . . . . . . . . . . . . . . Compiler notes
  42.     VI.A. . . . . . . . . . . . . . . .    Opcode and operand formats
  43.     VI.B. . . . . . . . . . . . . . . .    RPG II
  44.     VI.C. . . . . . . . . . . . . . . .    RPG III and RPG/400
  45.     VI.D. . . . . . . . . . . . . . . .    ASNA 400 RPG
  46.     VI.E. . . . . . . . . . . . . . . .    Lattice RPG II
  47.     VI.F. . . . . . . . . . . . . . . .    Native Software RPG 400
  48.     VI.G. . . . . . . . . . . . . . . .    BPS RPG II 1/2
  49.     VI.H. . . . . . . . . . . . . . . .    Other vendor extensions
  50.  
  51. VII.  . . . . . . . . . . . . . . . RPG/free translation notes
  52.  
  53. VIII. . . . . . . . . . . . . . . . RPG/pretty translation notes
  54.     VIII.A. . . . . . . . . . . . . . .    Handling of S/38 and AS/400 SRCDAT
  55.                           and SRCSEQ fields        
  56.     VIII.B. . . . . . . . . . . . . . .    Tab conversion        
  57.     VIII.C. . . . . . . . . . . . . . .    Program ID        
  58.     VIII.D. . . . . . . . . . . . . . .    Comments        
  59.     VIII.E. . . . . . . . . . . . . . .    Miscellaneous
  60.             
  61. IX. . . . . . . . . . . . . . . . . Reverse translation
  62.  
  63. X.  . . . . . . . . . . . . . . . . Implementation notes
  64.     X.A.  . . . . . . . . . . . . . . .    Maxima
  65.  
  66. XI. . . . . . . . . . . . . . . . . The RPG/free language
  67.     XI.A. . . . . . . . . . . . . . . .    Statements
  68.     XI.B. . . . . . . . . . . . . . . .    Comments
  69.     XI.C. . . . . . . . . . . . . . . .    Continuation
  70.     XI.D. . . . . . . . . . . . . . . .    Program structure
  71.     XI.E. . . . . . . . . . . . . . . .    Non-C-spec statements
  72.     XI.F. . . . . . . . . . . . . . . .    C-spec statements
  73.     XI.G. . . . . . . . . . . . . . . .    Multiple C-spec statements
  74.     XI.H. . . . . . . . . . . . . . . .    Sequence field (1-5)
  75.     XI.I. . . . . . . . . . . . . . . .    Control level indicator (7-8)
  76.     XI.J. . . . . . . . . . . . . . . .    Conditioning indicators (7-8 and 9-17)
  77.     XI.K. . . . . . . . . . . . . . . .    Operation (18-48)
  78.     XI.L. . . . . . . . . . . . . . . .    RPG/free operations
  79.     XI.M. . . . . . . . . . . . . . . .    Arithmetic assignments
  80.     XI.N. . . . . . . . . . . . . . . .    Keyword operations
  81.     XI.O. . . . . . . . . . . . . . . .    Opcode synonyms
  82.     XI.P. . . . . . . . . . . . . . . .    Operand keywords
  83.     XI.Q. . . . . . . . . . . . . . . .    Extended control structure operations
  84.     XI.R. . . . . . . . . . . . . . . .    Extended character assignment
  85.                             operations
  86.     XI.S. . . . . . . . . . . . . . . .    Declarations (49-52)
  87.     XI.T. . . . . . . . . . . . . . . .    DCL operation
  88.     XI.U. . . . . . . . . . . . . . . .    Half-adjust (53)
  89.     XI.V. . . . . . . . . . . . . . . .    Resulting indicators (54-59)
  90.  
  91. XII.  . . . . . . . . . . . . . . . Standard RPG directives
  92.  
  93. XIII. . . . . . . . . . . . . . . . RPG/free directives
  94.     XIII.A. . . . . . . . . . . . . . .    Setting the first column (/FIRSTCOL)
  95.     XIII.B. . . . . . . . . . . . . . .    Source macros (/DEFINE, /UNDEFINE, 
  96.                               and /DUMPMAC)
  97.     XIII.C. . . . . . . . . . . . . . .    Predefined language, compiler, and
  98.                               logical constant macros
  99.     XIII.D. . . . . . . . . . . . . . .    DOS command line macro definition
  100.                               (/define:xxx option)
  101.     XIII.E. . . . . . . . . . . . . . .    Conditional code generation
  102.                               (/IF, /ELSEIF, /ELSE, and /ENDIF)
  103.     XIII.F. . . . . . . . . . . . . . .    Fixed format input (/FIX and /FREE)
  104.     XIII.G. . . . . . . . . . . . . . .    Including source files 
  105.                               (/INCLUDE and /INCLUDEF)
  106.     XIII.H. . . . . . . . . . . . . . .    Combining macros and include files
  107.  
  108. XIV.  . . . . . . . . . . . . . . . The Future of RPG/free
  109.  
  110.  
  111.                  I. HOW TO USE THIS DOCUMENT            
  112.                 ---------------------------
  113.  
  114.      This document is an ASCII text file with <CR> at the end of each line.  
  115. Tab stops are the DOS defaults (9, 17, ...).  Because there are so many 
  116. variations in printer setups, this file contains no line or page spacing 
  117. other then tabs and blank lines.  If you want a "pretty" copy of the 
  118. document, import it into your favorite word processor before printing.
  119.  
  120.  
  121.                  II. INTRODUCTION
  122.                  ----------------
  123.  
  124.      RPG/free is a free format version of RPG.  The RPG/free precompiler 
  125. translates RPG/free input into standard RPG, which can be compiled by one of 
  126. the RPG compilers.  The RPG/pretty translator translates standard RPG input 
  127. into "pretty" RPG/free code.  Both RPG/free and RPG/pretty run under MS-DOS 
  128. or the DOS compatability box of OS/2.  There are also versions of 
  129. RPG/free and RPG/pretty that execute on the AS/400 and S/36.
  130.  
  131.      The executable versions of RPG/free and RPG/pretty covered by this 
  132. documentation can be freely copied and distributed.  They are commercial 
  133. quality programs intended for production use; however, because they are free, 
  134. no warranty or support is offered.  Please use normal care in backing up 
  135. files as you use these programs.
  136.  
  137.      If you find errors or have suggestions for improvements, please share 
  138. your knowledge.  By filling out the form in file FREENEWS, you can receive a
  139. free RPG/free newsletter that contains tips-and-techniques and error reports.
  140. The newsletter also contains the latest information on new releases
  141. of RPG/free and RPG/pretty.  The latest releases of the programs are available
  142. on the NEWSLINK bulletin board of NEWS 3X/400 magazine; for information on 
  143. NEWSLINK, call 800-373-3853.  (Other bulletin boards are free to copy the 
  144. latest releases from NEWSLINK to their own system for distribution.  My only 
  145. request of BBS operators is that you also provide the latest version of this 
  146. RFREE.DOC file along with the programs.)
  147.  
  148.  
  149.             III. INSTALLATION
  150.             -----------------
  151.  
  152.      To install from diskette, just copy RF.EXE (for RPG/free) and RP.EXE 
  153. (for RPG/pretty) to your PC hard disk.  (After you copy the two progams to 
  154. your hard disk, you may want to rename the programs to avoid accidentally 
  155. typing "RP" instead of "RF" when you execute them. For example, you might 
  156. rename RF.EXE to RFREE.EXE.)
  157.  
  158.      You can test the programs by executing:
  159.  
  160.     rf /listopt tstin1.rpf  tstin2.rpf  out.rpg
  161.     
  162.     rp /listopt tstin.rpg   out.rpf
  163.  
  164.      Then compare the generated file OUT.RPG with the supplied file 
  165. TSTOUT.RPG, and compare the generated file OUT.RPF with the supplied file 
  166. TSTOUT.RPF. These aren't comprehensive tests, but they will at least let you 
  167. know you have functioning versions of the programs.
  168.  
  169.      To de-install, just delete any files you no longer want to use.
  170.  
  171.  
  172.                 IV. EXECUTION
  173.                 -------------
  174.  
  175. IV.A. DOS COMMANDS:
  176.  
  177. RPG/free
  178.  
  179.     Memory requirements: Approximately 250K.
  180.  
  181.     Throughput: Approximately 1500 input lines per minute on an 
  182.                 IBM PS/2 Model 55SX (16Mhz) with 60Mb hard disk.
  183.  
  184.     Command:
  185.  
  186.     rf  [options]  input-file1  input-file2 ... input-filen  output-file
  187.  
  188.  
  189. RPG/pretty
  190.  
  191.     Memory requirements: Approximately 250K.
  192.  
  193.     Throughput: Approximately 300 input lines per minute on an 
  194.                 IBM PS/2 Model 55SX (16Mhz) with 60Mb hard disk.
  195.  
  196.     Command:
  197.  
  198.     rp  [options]  input-file  output-file
  199.  
  200.  
  201. For both programs:
  202.  
  203.     [options] is a list of options, each beginning with a slash (/).
  204.           (e.g., /cmtline:same)
  205.  
  206.     At least one input file and one output file are required, the last
  207.     file listed is the output file.  RPG/pretty can have up to 20 input
  208.     files (or your current DOS maximum open file limit).
  209.  
  210.     *** Be sure to include your output file when you use more than one 
  211.     *** RPG/free input file.  The command:  rf  inp1.rpf  inp2.rpf
  212.     *** treats inp2.rpf as the output file and replaces its contents.
  213.  
  214.     Use standard DOS file specifications for the input and output files.
  215.     You must include the extension when you specify a file.
  216.  
  217.     Recommended file extensions are:
  218.  
  219.         .RPG for standard RPG files
  220.         .RPF for RPG/free files
  221.         .RPI for included source files (other than macros)
  222.         .RPM for included macro files (discussed below)
  223.  
  224.  
  225. IV.B. ERROR FILES:
  226.  
  227.      Both programs write information, warning, and error messages to STDOUT.  
  228. You can use DOS output redirection to write messages to a disk file.  For 
  229. example:
  230.  
  231.     rf inp.rpf out.rpg > rf.err
  232.     
  233. will write all messages to rf.file.
  234.  
  235.      Translation warning and error messages have the same format as 
  236. Microsoft C compiler errors:
  237.  
  238.  
  239.     filespec (111): Warning 222: Message
  240.     filespec (111): Error 222: Message
  241.  
  242.     where:    111 is the input line number within filespec,
  243.         222 is the message identifier
  244.  
  245.      Many PC programming editors will automatically display warning 
  246. and error messages and position you to the source record that caused the 
  247. error.
  248.  
  249.  
  250. IV.C. RETURN STATUS:
  251.  
  252.      RPG/free and RPG/pretty return a DOS status value:
  253.  
  254.     -1 Command error or internal error
  255.      0 No error
  256.     10 Exit because /help option entered on command line
  257.     20 Translation warning
  258.     30 Translation error
  259.  
  260.      You can test the return status with IF ERRORLEVEL in DOS batch files.
  261.  
  262.  
  263. IV.D. RPG/free OPTIONS:
  264.  
  265. -- Execution options:
  266.  
  267. /help        List option switches.
  268.  
  269. /listopt    List the option settings for current execution.
  270.         Default is to not list option settings.
  271.  
  272. /errline    Output source line after error messages.
  273.         Default is to not output source line after error messages.
  274.  
  275. -- Formatting and translation options:
  276.  
  277. /cmtline:xxx    Output RPG/free comments (beginning with --) on previous 
  278.         or same line, where xxx is:     
  279.             none - Don't output comments
  280.                        prv  - Output comments before statement
  281.                        same - Output comments at end of statement
  282.         Default is /cmtline:prv.
  283.  
  284. /commadec    Decimal point is ',' instead of '.'
  285.         Default is '.' for decimal point.
  286.  
  287. /define:xxxxx    Define XXXXX as macro with value '@XXXX'.
  288.  
  289. /nocvttab    Do not convert tabs in input to spaces.
  290.         Default is to convert tabs using tab stops [9, 17, ...]
  291.  
  292. /numbers    Output RPG source line numbers in positions 1-5.
  293.         Default is to output blanks in 1-5.
  294.  
  295. /pgmid:xxxxxx    Output xxxxxx in program ID field (75-80).
  296. /pgmid:*BLANK    Output blanks in program ID.
  297.         Default is no program ID (75-80 may be used for comment text).
  298.  
  299. -- Source compiler options; use no more than one:
  300.  
  301.         Default is /rpgiii.
  302.  
  303. /asna        Output is Amalgamated Software of North America 400 RPG.
  304. /bps        Output is BPS Information Services RPG II 1/2.
  305. /cspi        Output is California Software Products Inc. RPG II.
  306. /cspi400    Output is California Software Products Inc. RPG 400.
  307. /lattice    Output is Lattice, Inc. RPG II.
  308. /native        Output is Native Software RPG 400.
  309. /rpgii        Output is IBM RPG II  (or 100% compatible).
  310. /rpgiii        Output is IBM RPG III (or 100% compatible).
  311. /rpg400        Output is IBM RPG/400 (or 100% compatible).
  312. /softwest    Output is Software West RPG II.
  313. /trident    Output is Trident Software, Inc. RPG III.
  314.  
  315.  
  316. IV.E. RPG/pretty OPTIONS:
  317.  
  318. -- Execution options:
  319.  
  320. /help        List option switches.
  321.  
  322. /listopt    List the option settings for current execution.
  323.  
  324. /errline    Output source line after error messages.
  325.         Default is to not output source line after error messages.
  326.  
  327. -- Formatting and translation options:
  328.  
  329.  /cmtline:xxx    Output C-spec comment field (beginning in position 60) on 
  330.          previous or same line, where xxx is:
  331.             none - Don't output comments
  332.              prv  - Output comment before statement
  333.                        same - Output comment at end of statement
  334.         Default is /cmtline:same.
  335.  
  336. /cvttab        Convert tabs in input to spaces using tab stops [9, 17, ...].
  337.         Default is to not convert tabs in input.
  338.  
  339. /idcap        Output identifiers with initial letter in upper case and other
  340.         letters in lower case.
  341. /idupper    Output identifiers in upper case.
  342.         Default is lower case.
  343.  
  344. /ignpid        Do not output the program ID (positions 75-80) as comment.
  345.         Default is to output non-blank contents of 75-80 as comment.
  346.  
  347. /ignmsglines    Do not output lines with embedded compiler messages.
  348.         Default is to output message lines.
  349.  
  350. /indent:Nb    Use N blanks for each indent.
  351. /indent:Nt    Use N tabs for each indent.
  352.         Default is 1 tab.
  353.  
  354. /kwdlower    Output keywords in lower case.
  355.         Default is upper case.
  356.  
  357. /maxindent:N    Maximum indent is N levels.
  358.         Default is 5.
  359.  
  360. /nbr:xxx    Output statement numbers (positions 1-5), where xxx is:
  361.             all      - Output all statement numbers
  362.             ignore   - Don't output any statement numbers, 
  363.                    no warning
  364.             nonblank - Output nonblank statement numbers
  365.             warn     - Don't output any statement numbers, 
  366.                    give warning
  367.             Default is /nbr:warn
  368.  
  369. /nodir        Do not reverse translate commented RPG/free directives.
  370.         Default is to reverse translate commented RPG/free form-type
  371.         directives, /FIRSTCOL, /FIX, and /FREE.
  372.  
  373. /noform        Begin H, F, E, I, T, L, O, and U spec output in position 7.
  374.         You cannot use /noform and /nbr:all together.
  375.         Default is position 6 (form type character).
  376.  
  377. /sep:Nb        Use N blanks between operands.
  378. /sep:Nt        Use N tabs between operands.
  379.         Default is 1 tab.
  380.  
  381. /symind        Output indicators in symbolic form (*INxx).
  382.         Default is nonsymbolic form (xx).
  383.  
  384. /trimcmt    Trim leading blanks from comments.
  385.         Default is to leave leading blanks in comments.
  386.  
  387. -- Source compiler options; use no more than one:
  388.  
  389.         Default is /rpgiii.
  390.  
  391. /asna        Input is Amalgamated Software of North America 400 RPG.
  392. /bps        Input is BPS Information Services RPG II 1/2.
  393. /cspi        Input is California Software Products Inc. RPG II.
  394. /cspi400    Input is California Software Products Inc. RPG 400.
  395. /lattice    Input is Lattice, Inc. RPG II.
  396. /native        Input is Native Software RPG 400.
  397. /rpgii        Input is IBM RPG II  (or 100% compatible).
  398. /rpgiii        Input is IBM RPG III (or 100% compatible).
  399. /rpg400        Input is IBM RPG/400 (or 100% compatible).
  400. /softwest    Input is Software West RPG II.
  401. /trident    Input is Trident Software, Inc. RPG III.
  402.  
  403.                   
  404.         V. WHAT'S NEW IN VERSION 2.0, 2.01, and 2.02
  405.         --------------------------------------------
  406.  
  407. Version 2.0 was initially released as a Beta version.  Version 2.02
  408. is the current distribution version.  Version 2.0-Beta and 2.02
  409. have the following changes from the previous release (V1.0).
  410.  
  411.  
  412. -- Input and output line size increased to 250 characters.
  413.  
  414. -- Formatting
  415.  
  416.    A number of changes were made to enhance "reverse" translation.
  417.  
  418.    RPG/pretty supports "reverse" translation of RPG/free form type
  419.    directives, and /FIX, /FREE, /INCLUDE, and /INCLUDEF.
  420.  
  421.    RPG/free generates /ENDINCLUDE and /ENDINCLUDEF to mark end of
  422.    included code. 
  423.    
  424.    RPG/pretty /ignpgmid option and RPG/free /pgmid:xxx option, and new 
  425.    formatting of program ID field. 
  426.  
  427.    /cmtline:xxx options and new comment formatting. 
  428.  
  429.    Blank lines are formatted differently.
  430.    
  431.    /commadec option to use ',' as decimal point.
  432.    
  433. -- /AUTORPT form type directive added to support U-specs. 
  434.  
  435. -- Error messages 
  436.  
  437.    New message format, similar to Microsoft C compiler errors, for automated 
  438.    handling by PC editors.
  439.  
  440.    Error messages are written to STDOUT instead of STDERR.
  441.  
  442.    All error messages have a unique number identifying the error.
  443.  
  444.    RPG/free and RPG/pretty return non-zero values if a warning or error 
  445.    occurs during translation.
  446.  
  447.    /errline option to control printing of source line with error messages.
  448.  
  449. -- Multiple C-spec operations can be coded on a single input statement.
  450.  
  451. -- Macros
  452.  
  453.    Replacement text can now be continued across multiple input lines and can 
  454.    be up to 250 characters (v1.0 limit was 100).
  455.  
  456.    Replacement text can include multiple C-spec operations.
  457.  
  458.    RPG/free comments (beginning with --) can be coded on /DEFINE directive.
  459.  
  460.    /DUMPMAC directive writes current macro table to disk file.
  461.  
  462.    /DEFINE x ... generates error if x is already defined (v1.0 redefined x).
  463.  
  464.    /define:xxx command line option defines XXXX as a macro with 
  465.    replacement text '@XXX'.
  466.  
  467.    Macros are automatically defined for language version (e.g., ASNA)
  468.    and compiler (e.g., RPGIII).
  469.  
  470.    Macro names can begin with underscore (e.g., _mymac).
  471.  
  472.    TO macro is automatically installed with blank replacement text (for
  473.    use as "noise" word in operations like MOVE x TO y).
  474.    
  475. -- Special values
  476.  
  477.    *TRUE generates '1'; *FALSE generates '0'.
  478.  
  479. -- C-spec sequence field can be coded as:   {ABC}
  480.  
  481. -- LEVEL(*INL0) or LVL(*INL0) can be used for C-spec control indicator.
  482.  
  483. -- Conditional translation
  484.  
  485.    Conditional directives: /IF [NOT] DEFINED(macro), 
  486.    /ELSEIF [NOT] DEFINED(macro), /ELSE, and /ENDIF allow conditional 
  487.    translation of code and data.
  488.    
  489. -- Non-commented text after RPG/free directives now generates warning. 
  490.  
  491. -- IBM RPG/400
  492.  
  493.    Release 3.0 opcodes supported: CAT, CLEAR, RESET, SCAN, SUBST
  494.  
  495.    String references like X:I supported.
  496.  
  497.    READE and REDPE optional Factor1 supported.
  498.  
  499.    New special values supported: *INZSR, *NOKEY, *PDA
  500.    
  501. -- ASNA 400 RPG
  502.  
  503.    USE opcode supported.
  504.  
  505.    Factor 1 on EDIT operation can now have form:   *11
  506.  
  507.    /PRINT directive supported.
  508.    
  509. -- Extended assignment operations
  510.  
  511.    XMOVE, XSUBST (RPG/400), XCAT (RPG/400), XCATST (Lattice) operations
  512.    clear Result before assignment.
  513.    
  514. -- Extended control structures
  515.  
  516.    LOOP, BREAK, CONTINUE, EXITSR, and EXITBLOCK operations support new
  517.    control structures.
  518.    
  519. -- New opcode synonyms: BITOFF, ENDLOOP, XCATSTR, XSUBSTR.
  520.  
  521. -- New resulting indicator keywords for positions 58-59: FND, FOUND
  522.  
  523. -- New synonyms for F1(), F2(), and R() operand keywords.
  524.    For example:    READE  KEY( custid )  FMT( cusrcd ) 
  525.  
  526. -- Dropped or changed options
  527.  
  528.    RPG/pretty
  529.    
  530.      /indentNb      is replaced by   /indent:Nb    
  531.      /indentNt      is replaced by   /indent:Nt    
  532.      /isn      is replaced by   /nbr:ignore
  533.      /maxindentN  is replaced by   /maxindent:N
  534.      /sepNb      is replaced by   /sep:Nb    
  535.      /sepNt      is replaced by   /sep:Nt    
  536.                       
  537.    RPG/free               
  538.                       
  539.      /nocmt      is replaced by   /cmtline:none 
  540.  
  541.  
  542. Version 2.01 has the following changes from V2.0-Beta.
  543.  
  544. -- Formatting
  545.  
  546.    An extra blank line is no longer emitted after opcodes that have
  547.    no operands (e.g., RETURN)
  548.  
  549.    C-spec lines that have only a sequence number and a comment now have
  550.    the comment formatted like a C-spec line with only a comment.
  551.    
  552. -- Comments that immediately follow a directive are now handled
  553.    properly (e.g.,   /DATA--Comment    ).  Previously, the directive
  554.    was not recognized unless it was followed by a blank or tab. 
  555.  
  556. -- Macros
  557.  
  558.    A defect in v2.0-Beta truncated without warning macro replacement text
  559.    that exceeded the limits.  Proper warnings are now generated.
  560.  
  561.    Maximum macro name length is 30 characters (previous versions 
  562.    allowed 80, the limit was lowered to allow longer replacement text
  563.    and more macro definitions).
  564.  
  565.    Maximum macro definitions is now 200 (v2.0-Beta limit was 100).
  566.  
  567.    %SYSSYMBOL built-in macro function is available for automatically 
  568.    generating standard RPG field names and preventing accidental
  569.    duplicate use of RPG field names for different macros.
  570.  
  571.    /DUMPMAC directive writes current macro table to disk file --
  572.    The format for each macro is:  [macroname] [replacement text] [x]
  573.    where x is 'S' for %SYSSYMBOL-defined macros and blank otherwise.
  574.  
  575.    A set of macros for the RPG/free version, the target standard RPG
  576.    language, and the target RPG compiler are installed.  Several
  577.    macros are added that weren't in v2.0-Beta, and the format of the
  578.    macro names has been changed to begin and end with underscores.
  579.  
  580. -- Conditional translation
  581.  
  582.    A defect in the parsing of /IF DEFINED(macro) is fixed.  v2.0-Beta
  583.    failed unless macro name had surrounding blanks.
  584.  
  585. -- Extended assignment operations
  586.  
  587.    XSUBST (RPG/400), XCAT (RPG/400), XCATST (Lattice) operations
  588.    generate a warning if the Result operand is the same as either
  589.    Factor1 or Factor2, because XCAT, XCATST, and XSUBST move
  590.    blanks to the REsult before the string operation.
  591.    
  592. -- Extended control structures
  593.  
  594.    ELSEIF is installed as a macro with "ELSE; IF " as it's 
  595.    replacement text. 
  596.  
  597.    Three "logical operator" special values are installed as built-in
  598.    macros that can be used with control structures such as IF:
  599.  
  600.    Special value    Replacement text
  601.    -------------    ----------------
  602.    *AND            ;AND
  603.    *OR            ;OR
  604.    *NOT            IF *TRUE <>
  605.  
  606.  
  607. Version 2.02 has the following changes from V2.01.
  608.  
  609. -- A cosmetic change in an error message in RPG/pretty
  610.  
  611.  
  612.  
  613.  
  614.             VI. COMPILER NOTES
  615.             ------------------
  616.  
  617. VI.A. OPCODE AND OPERAND FORMATS:
  618.  
  619.      The following tables shows how RPG/free treats operation arguments:
  620.  
  621.                                                   Logical
  622.     Operation     Factor1   Factor2   Result    Operator  Notes
  623.     ---------     --------  --------  --------  --------      --------------
  624.     ACQ           Required  Required    --        --      
  625.     ADD           Optional  Required  Required    --      
  626.     AND           Required  Optional    --      Optional      Extended op
  627.     ANDxx         Required  Required    --        --      
  628.     BEGSR         Required    --        --        --      
  629.     BITOF           --      Required  Required    --      
  630.     BITON           --      Required  Required    --      
  631.     BREAK           --        --        --        --       Extended op
  632.     CABxx         Required  Required  Optional    --      
  633.     CALL            --      Required  Optional    --      
  634.     CAS           Optional  Optional  Required    --      
  635.     CASE          Optional  Optional  Required  Optional      Extended op
  636.     CASxx         Optional  Optional  Required    --      
  637.     CAT           Required  Required  Required    --          R3.0 RPG/400
  638.     CATST         Required  Required  Required    --          Lattice
  639.     CHAIN         Required  Required  Optional    --      
  640.     CKDT            --      Required  Required    --          ASNA
  641.     CLEAR         Optional  Required    --        --      
  642.     CLOSE           --      Required    --        --      
  643.     COMIT         Optional    --        --        --      
  644.     COMP          Required  Required    --        --      
  645.     CONTINUE        --        --        --        --          Extended op
  646.     CVDT          Required  Required  Required    --          ASNA
  647.     DCL             --      Optional  Required    --          Extended op
  648.     DEBUG         Optional  Optional  Optional    --          RPG III/400
  649.     DEBUG         Optional  Required  Optional    --          RPG II
  650.     DEFN          Required  Optional  Required    --          RPG III/400
  651.     DEFN          Required  Required  Required    --          RPG II
  652.     DELET         Optional  Required    --        --      
  653.     DIV           Optional  Required  Required    --      
  654.     DO            Optional  Optional  Optional    --      
  655.     DOUxx         Required  Required    --        --      
  656.     DOWxx         Required  Required    --        --      
  657.     DSPLY         Optional  Optional  Optional    --      
  658.     DUMP          Optional    --        --        --      
  659.     EDIT          Required  Required  Required    --          ASNA
  660.     ELSE            --        --        --        --      
  661.     END             --      Optional    --        --      
  662.     ENDSR         Optional  Optional    --        --      
  663.     ENDSS           --      Required  Required    --          Lattice
  664.     EXCPT           --      Optional    --        --      
  665.     EXFMT           --      Required    --        --      
  666.     EXIT            --      Required    --        --          RPG II
  667.     EXITBLOCK       --        --        --        --          Extended op
  668.     EXSR            --      Required    --        --      
  669.     FEOD            --      Required    --        --      
  670.     FOR           Required  Required  Required  Required      Extended op
  671.     FORCE           --      Required    --        --      
  672.     FREE            --      Required    --        --      
  673.     GOTO            --      Required    --        --      
  674.     IF            Required  Optional    --      Optional      Extended op
  675.     IFxx          Required  Required    --        --      
  676.     IN            Optional  Required    --        --      
  677.     KEYxx         Optional    --      Optional    --          RPG II
  678.     KFLD            --        --      Required    --      
  679.     KLIST         Required    --        --        --      
  680.     LOKUP         Required  Required  Optional    --      
  681.     LOOP            --        --        --        --          Extended op
  682.     MHHZO           --      Required  Required    --      
  683.     MHLZO           --      Required  Required    --      
  684.     MLHZO           --      Required  Required    --      
  685.     MLLZO           --      Required  Required    --      
  686.     MODE            --      Required    --        --          Native Software
  687.     MOVEx           --      Required  Required    --      
  688.     MULT          Optional  Required  Required    --      
  689.     MVR             --        --      Required    --      
  690.     NEXT          Required  Required    --        --      
  691.     OCUR          Optional  Required  Optional    --      
  692.     OPEN            --      Required    --        --      
  693.     OR            Required  Optional    --      Optional      Extended op
  694.     ORxx          Required  Required    --        --      
  695.     OUT           Optional  Required    --        --      
  696.     PARM          Optional  Optional  Required    --      
  697.     PLIST         Required    --        --        --      
  698.     POST          Optional  Optional  Optional    --          RPG III/400
  699.     POST          Required    --      Required    --          RPG II
  700.     RDCOM           --        --      Required    --          Native Software
  701.     READ            --      Required  Optional    --      
  702.     READC           --      Required    --        --      
  703.     READE         Optional  Required  Optional    --          R3.0 RPG/400
  704.     READE         Required  Required  Optional    --          RPG III
  705.     READP           --      Required  Optional    --      
  706.     REDPE         Optional  Required  Optional    --          R3.0 RPG/400
  707.     REDPE         Required  Required  Optional    --          RPG III
  708.     REL           Required  Required    --        --      
  709.     RESET         Optional  Required    --        --      
  710.     RETRN           --        --        --        --      
  711.     RLABL           --        --      Required    --          RPG II
  712.     ROLBK           --        --        --        --      
  713.     SCAN          Required  Required  Optional    --      
  714.     SETGT         Required  Required    --        --      
  715.     SETLL         Required  Required    --        --      
  716.     SETOF           --        --        --        --      
  717.     SETON           --        --        --        --      
  718.     SETxx         Optional  Optional  Optional    --          RPG II
  719.     SHTDN           --        --        --        --      
  720.     SORTA           --      Required    --        --      
  721.     SQRT            --      Required  Required    --      
  722.     SUB           Optional  Required  Required    --      
  723.     SUBST         Required  Required  Required    --          R3.0 RPG/400
  724.     SUBST         Required  Required    --        --          Lattice
  725.     TAG           Required    --        --        --      
  726.     TESTB           --      Required  Required    --      
  727.     TESTN           --        --      Required    --      
  728.     TESTZ           --        --      Required    --      
  729.     TIME            --        --      Required    --      
  730.     UNLCK           --      Required    --        --      
  731.     UNTIL         Required  Optional    --      Optional      Extended op
  732.     UPDAT           --      Required  Optional    --      
  733.     USE             --      Required    --        --          ASNA
  734.     WAIT            --      Required    --        --          ASNA
  735.     WHILE         Required  Optional    --      Optional      Extended op
  736.     WRCOM           --      Required    --        --          Native Software
  737.     WRITE           --      Required  Optional    --      
  738.     XCAT          Required  Required  Required    --          Extended op -
  739.                                          RPG/400
  740.     XCATST        Required  Required  Required    --          Extended op -
  741.                                          Lattice
  742.     XFOOT           --      Required  Required    --      
  743.     XMOVE           --      Required  Required    --          Extended op
  744.     XSUBST        Required  Required  Required    --          Extended op -
  745.                                          RPG/400
  746.     Z-ADD           --      Required  Required    --      
  747.     Z-SUB           --      Required  Required    --      
  748.  
  749.  
  750.  
  751. VI.B. RPG II:
  752.  
  753.      Most RPG II opcodes are handled fine with the default /rpgiii compiler 
  754. type. The following opcodes may require /rpgii or one of the third-party 
  755. RPG II compiler options (depending on which operands you use for Factor1, 
  756. Factor2, and Result):
  757.  
  758.     DEBUG
  759.     DEFN
  760.     POST
  761.  
  762.      The /rpgii option is required for the following translations:
  763.  
  764.      -- RPG/pretty
  765.  
  766.     Recognize ** in positions 1-2 with non-blank in 3 as beginning of 
  767.     data.  (Default /rpgiii    requires position 3 to be blank.)
  768.         
  769.     Recognize /* in positions 1-2 as end-of-file.
  770.  
  771.     Handle embedded compiler messages that begin with ??x.
  772.  
  773.  
  774. VI.C. RPG III and RPG/400:
  775.  
  776.      Release 3.0 of RPG/400 changed Factor1 from a required operand to an 
  777. optional operand on READE and REDPE2, so you will need the /rpg400 switch 
  778. if you do not use Factor1.  
  779.  
  780.      You do not need to use /rpg400 to use the new RPG/400 opcodes such as 
  781. CLEAR and SUBST.
  782.  
  783.  
  784. VI.D. ASNA 400 RPG:
  785.  
  786. ASNA                Indicator Keywords
  787. Opcode    Factor1    Factor2    Result    54-55 56-57 58-59
  788. ------    -------    -------    ------    ----- ----- -----
  789. CKDT    Blank    Rqd    Rqd
  790. CVDT    Rqd    Rqd    Rqd
  791. EDIT    Rqd    Rqd    Rqd
  792. USE    Blank    Rqd    Blank
  793. WAIT    Blank    Rqd    Blank
  794.  
  795. /PRINT GEN        Compiler directive
  796. /PRINT NOGEN
  797.  
  798.  
  799.      The /asna option is required for the following translations:
  800.      
  801.      -- RPG/free
  802.  
  803.     EDIT opcode Factor1 edit code operands like *11.
  804.  
  805.      -- RPG/pretty
  806.  
  807.     Required to handle embedded compiler messages that have an 
  808.     accent (`) in position 6. 
  809.  
  810.  
  811. VI.E. LATTICE RPG II:
  812.  
  813. Vendor    RPG/free                Indicator Keywords
  814. Opcode    Synonym        Factor1    Factor2    Result    54-55 56-57 58-59
  815. ------    -----------    -------    -------    ------    ----- ----- -----
  816. blank    ENDSS or    Blank    Rqd    Rqd
  817.     ENDSUBSTR
  818. CATST    CATSTR        Rqd    Rqd    Rqd
  819. SUBST    SUBSTR        Rqd    Rqd    Blank
  820. MOVE    XCATSTR        Rqd    Rqd    Rqd
  821. CATST
  822.  
  823.      Note that XCATSTR generates a MOVE *BLANK and a CATST. Lattice does not 
  824. support XSUBSTR because the Lattice version of the substring operation spans 
  825. two RPG/free C-spec statements.
  826.  
  827.      The /lattice option is required for the following translations:
  828.      
  829.      -- RPG/free
  830.  
  831.         Hexadecimal constants like  X'FFFF....'  into  X'FFFF....
  832.  
  833.     CATSTR and XCATSTR to Lattice CATST opcode.        
  834.  
  835.     ENDSS to blank opcode.
  836.  
  837.     Distinguish Lattice and RPG/400 variations of SUBST opcode.
  838.  
  839.      -- RPG/pretty
  840.  
  841.         Hexadecimal constants like  X'FFFF....  into  X'FFFF....'
  842.  
  843.     Blank opcode following SUBST to ENDSUBSTR.
  844.  
  845.     Distinguish Lattice and RPG/400 variations of SUBST opcode.
  846.  
  847.      If you use a Lattice "compressed" file as input to RPG/pretty, you
  848.      should use the /cvttab option.
  849.  
  850.  
  851. VI.F. NATIVE SOFTWARE RPG 400:
  852.  
  853. Vendor                Indicator Keywords
  854. Opcode    Factor1    Factor2    Result    54-55 56-57 58-59
  855. ------    -------    -------    ------    ----- ----- -----
  856. MODE    Blank    Rqd    Blank                RI3
  857. RDCOM    Blank    Blank    Rqd    RI1   RI2   RI3
  858. WRCOM    Blank    Rqd    Blank          RI2   RI3
  859.  
  860.  
  861. VI.G. BPS RPG II 1/2:
  862.  
  863.      BPS RPG II 1/2 is an RPG II precompiler that uses some non-standard 
  864. statement formats.  RPG/free and RPG/pretty do not support RPG II 1/2 
  865. ten-character Result fields; macro definitions; or macro variables.  Before 
  866. running RPG II 1/2 code through RPG/pretty, you should bracket non-standard 
  867. statements with */FIX and */FREE.  RPG/pretty will then generate 
  868. fixed-format RPG/free source and the appropriate /FIX and /FREE directives.
  869.  
  870.      The /bps option is required for the following translations:
  871.  
  872.      -- RPG/pretty
  873.  
  874.     To recognize *? in positions 1-2 as beginning of data. 
  875.  
  876.  
  877. VI.H. OTHER VENDOR EXTENSIONS:
  878.  
  879.      If you encounter a vendor extension that is not properly handled by 
  880. RPG/free's translation, the ultimate "work-around" is to use a /FIX 
  881. directive, followed by the exact format of the standard RPG statement, 
  882. followed by a /FREE directive.
  883.  
  884.  
  885.             VII. RPG/free TRANSLATION NOTES
  886.             -------------------------------
  887.  
  888.      RPG/free does not translate non-C-spec input to uppercase.  You should 
  889. use uppercase wherever standard RPG requires it in non-C-specs.
  890.  
  891.      Tabs are converted to blanks on input using DOS default tabstops 
  892. (9, 17, ...). The /nocvttab option eliminates conversion.  The only 
  893. place where you might encounter problems are in non-C-specs or quoted 
  894. literals, if you are using different tab stops than the defaults.  Just 
  895. replace any problem tabs with appropriate spaces.
  896.  
  897.      Some error messages list the current token as seen by the parser.  You 
  898. may see the following "strange" symbols:
  899.  
  900.     EOS    End of string (the end of the input statement)
  901.     U+    Unary plus  (as in X = + Y)
  902.     U-    Unary minus (as in X = - Y)
  903.  
  904.      In some cases, the translator pushes the current token back on the input 
  905. stream and re-parses it.  This may cause you to see two or more error 
  906. messages for the same token (for example when there is an unclosed string in 
  907. the input).
  908.  
  909.  
  910.              VIII. RPG/pretty TRANSLATION NOTES
  911.              ----------------------------------
  912.  
  913. VIII.A. HANDLING OF S/38 AND AS/400 SRCDAT AND SRCSEQ FIELDS:
  914.  
  915.      RPG/pretty determines where position 1 of the standard RPG specification 
  916. is in the DOS file by examining the first input record to see if there are 
  917. S/38 or AS/400 SEU-style source numbers or dates (not the RPG statement 
  918. numbers in RPG positions 1-5). These source numbers and dates are normally 
  919. stripped when you use PC Support on the S/38 or AS/400 to download a source 
  920. file member.  But if they are included, RPG/pretty can normally figure out 
  921. how to skip them.  
  922.  
  923.      If you want to preserve the SRCDAT field for S/38 or AS/400 source 
  924. files, you can use two DOS utilities: Date/pretty and Date/free.  These 
  925. utilities, along with their documentation and source code are available on 
  926. the NEWSLINK BBS.  They are Awk programs and can only be used with DOS or 
  927. OS/2.  
  928.  
  929. The rules RPG/pretty uses are:
  930.  
  931.     IF    characters 1-8  contain xxxxx.nn AND
  932.         characters 9-15 contain xxxxxxn
  933.  
  934.         The RPG statement starts in 16
  935.  
  936.     ELSE IF    characters 1-7  contain xxxxxxn  AND
  937.         characters 8-15 contain xxxxx.nn
  938.  
  939.         The RPG statement starts in 16
  940.  
  941.     ELSE IF    characters 1-8  contain xxxxx.nn
  942.  
  943.         The RPG statement starts in 9
  944.  
  945.     ELSE IF    characters 1-7  contain xxxxxxn
  946.  
  947.         The RPG statement starts in 8
  948.  
  949.     ELSE    The RPG statement starts in 1
  950.  
  951.     (Where each  n  is a digit and each  x  is a digit or blank.)
  952.  
  953.      After finding the beginning position, RPG/free uses similar logic 
  954. to check the tail of the first statement to find the ending position.  If no 
  955. SRCDAT or SRCSEQ field is found at the end of the first statement, the 
  956. statement ending is the end-of-line character.
  957.  
  958.      If you have problems, just strip off any non-RPG line numbers.  (Do NOT
  959. strip off RPG statement numbers in positions 1-5; use the /nbr:ignore option 
  960. to ignore them.)
  961.  
  962.  
  963. VIII.B. TAB CONVERSION:
  964.  
  965.      RPG/pretty does not normally convert tabs to blanks on input.  If you 
  966. use Lattice "compressed" source (the Lattice default), you should use the 
  967. /cvttab to force RPG/pretty to convert tabs to blanks.
  968.  
  969.  
  970. VIII.C. PROGRAM ID:
  971.  
  972.      If you specify /ignpid, RPG/pretty cuts out the program ID (positions 
  973. 75-80) for all input lines except: input following the data sentinel (e.g., 
  974. **) and non-commented H-specs.  Any non-blank input beyond position 80 is 
  975. concatenated to the statement up to position 74.
  976.  
  977.  
  978. VIII.D. COMMENTS:
  979.  
  980.      Comment lines that are not C-specs are output as the formtype followed 
  981. by an asterisk (with /noform, just an asterisk).  For example,
  982.  
  983.     F* comment...
  984.  
  985.      You may want to use a PC editor to search and replace this pattern 
  986. (e.g., F*) with  --  which is the standard RPG/free comment.  The current 
  987. RPG/pretty approach maintains better alignment for commented non-C-specs in 
  988. existing code.
  989.  
  990.      C-spec comments beginning in position 60 are output as a trailing 
  991. comment (using --) following the operation when you use /cmtline:same. With 
  992. /cmtline:prv, comments are output on a separate line before the operation 
  993. and are indented to line-up with the operation.
  994.  
  995.      The cmtline:xxx option applies only to comments in positions 60 or 
  996. higher of a C-spec.  Standalone comments (e.g., F* Comment ... ) are always
  997. output on the same line.
  998.  
  999.  
  1000. VIII.E. MISCELLANEOUS:
  1001.  
  1002.      Some invalid specifications do not cause a warning; for example, an 
  1003. indicator like UX is considered valid.  RPG/free will catch many of these.
  1004.  
  1005.      All opcode lookups are done in UPPERCASE (as standard RPG requires).
  1006.  
  1007.  
  1008.             IX. REVERSE TRANSLATION
  1009.             ------------------------
  1010.  
  1011.      Version 2.0 will reverse translate many basic RPG and RPG/free programs.  
  1012. However, several powerful features of RPG/free cannot be reverse translated.  
  1013. If you must maintain a standard RPG version of a program so that it can be 
  1014. edited, the following guidelines will help you.  I would recommend you avoid 
  1015. editing the standard RPG code, if possible, because that will let you take 
  1016. advantage of all of RPG/free's productivity enhancements. 
  1017.  
  1018.      To repeatedly cycle a program through RPG/pretty and RPG/free, You 
  1019. must use /cmtline:same option with both RPG/free and RPG/pretty to 
  1020. get reversible comment format.  Do NOT use the RPG/pretty /nodir, or /trimcmt 
  1021. options.  
  1022.  
  1023.      Use the following RPG/pretty switches, as needed:
  1024.  
  1025.     /cvttab        If your standard RPG includes tab characters
  1026.     /ignmsglines    If your input contains embedded compiler messages
  1027.     /ignpid        If you have the program ID in positions 75-80
  1028.     /nbr:nonblank    If you have data in positions 1-5 of source
  1029.  
  1030.      Use the following RPG/free switche, as needed:
  1031.  
  1032.     /pgmid:xxx    If your standard RPG program has a program ID
  1033.  
  1034.      Use the standard comment style (e.g.,  F* Comment... ) for comments 
  1035. that are not within the C-specs.
  1036.  
  1037.      RPG/free does not reverse translate code generated by 
  1038. the following RPG/free features: macro definition and expansion (/DEFINE 
  1039. etc.); conditional translation (/IF DEFINED, etc.); extended control 
  1040. structures (LOOP, BREAK, CONTINUE, EXITBLOCK); extended assignment 
  1041. operations (XMOVE, XCAT, XCATST, XSUBST); DCL free-standing declarations; 
  1042. *TRUE and *FALSE special values; 
  1043.  
  1044.      RPG/free translates C-spec operands into RPG/free positional format, not 
  1045. keyworded format (e.g., F1, FMT, etc.).
  1046.  
  1047.      You may need to cycle your program once before it is in a format that 
  1048. will reverse exactly.  Both RPG/pretty and RPG/free make some minor shifts
  1049. to put things in a standard form for reverse translation. 
  1050.  
  1051.                  
  1052.             X. IMPLEMENTATION NOTES
  1053.             -----------------------
  1054.  
  1055. This version of RPG/pretty is implemented with PolyAWK compiler v. 1.1BETA.
  1056. This version of RPG/free   is implemented with Microsoft QuickC v. 2.51.
  1057.  
  1058. Both programs were implemented on an IBM PS/2 Model 55SX with IBM PC-DOS 4.01.
  1059.  
  1060. X.A. MAXIMA:
  1061.  
  1062.      RPG/free has the following maxima:
  1063.  
  1064.     Input files                    20 (or DOS limit)
  1065.     File name length                90
  1066.     Number of command line arguments        20
  1067.     Command argument length                90
  1068.     Number of continuation lines            19
  1069.     Input line length               250
  1070.     Output line length               250
  1071.     Statement length              1000
  1072.     Keyword length                    20
  1073.     Token length                    80
  1074.     Macro name length                30
  1075.     Macro replacement text length           250
  1076.     Number of macros               200
  1077.     Nesting levels for conditional directives   20
  1078.     Nesting levels for control structures        20
  1079.  
  1080.  
  1081.      RPG/pretty has the following maxima:
  1082.  
  1083.     Input files                     1
  1084.     File name length                90
  1085.     Number of command line arguments        20
  1086.     Command argument length                90
  1087.     Input line length               250
  1088.     Output line length               250
  1089.     Statement length              1000
  1090.     Nesting levels for control structures        20
  1091.  
  1092.  
  1093.  
  1094.             XI. THE RPG/free LANGUAGE
  1095.             -------------------------
  1096.  
  1097.      An introduction to RPG/free is published in the article "RPG/free -- The 
  1098. Golden Age of RPG Programming", Paul Conte, NEWS 3X/400, April 1990.  Copies 
  1099. of this article are available as a back issue order from NEWS 3X/400, P.O. 
  1100. Box 3438, Loveland, CO 80539-9916 (800) 373-3853.  The article covers   
  1101. version 1.0.
  1102.  
  1103. XI.A. STATEMENTS
  1104.  
  1105.      An RPG/free program consists of a file of "statements".  Most RPG/free 
  1106. statements can be continued across multiple input lines.  Statements include:
  1107.  
  1108.     Statement type            Example
  1109.     ---------------------------    ------------------------------------
  1110.     RPG/free directives        /CALC, /DEFINE    
  1111.     Standard RPG directives        /TITLE, /EXEC SQL
  1112.     SQL statements            SELECT * FROM CUST
  1113.     Non-C-spec             FCUST    I   E       DISK
  1114.     Commented non-C-spec        *F Comment
  1115.     C-spec assignment        x = y
  1116.     C-spec keyword operation    READ cust EOF( eof_cust )
  1117.     RPG/free comment line        -- Comment
  1118.     Blank line
  1119.     Data                Abcdef...
  1120.  
  1121.  
  1122. XI.B. COMMENTS
  1123.  
  1124.      You can add a trailing comment to any RPG/free statement, except the 
  1125. /EXEC SQL and /TITLE directives and SQL statements between /EXEC SQL and 
  1126. /END-EXEC.  Comments can be added to other directives and non-C-specs, as 
  1127. well as C-specs.  You cannot add comments to lines that follow the /DATA 
  1128. directive, lines between /FIX and /FREE directives, or lines in a file 
  1129. included with the /INCLUDEF directive.  (You can place comments on lines in 
  1130. a file included with the /INCLUDE directive.)
  1131.  
  1132.      Use two adjacent dashes (--) to begin a comment.  For example:
  1133.  
  1134.     add a b -- This is a comment
  1135.  
  1136.      The comment ends at the end of the input line or at the last character 
  1137. before a plus sign (+) indicates a continued statement.  The first 
  1138. unquoted -- in a line marks the beginning of the comment.  Although you can 
  1139. generally leave blanks out of assignment operations (e.g., a=b-c), don't code 
  1140. "b minus -3" as  b--3 because the --3 will be treated as a comment.
  1141.  
  1142.      You cannot place comments (or any --) WITHIN the replacement text of a 
  1143. macro because comments are stripped from the macro definition as the input 
  1144. lines are read.  You can have comments on the macro definition statement 
  1145. itself, which is generally all you need for macro documentation.
  1146.  
  1147.      To code a comment line, just begin with -- anywhere in the line.
  1148.  
  1149.  
  1150. XI.C. CONTINUATION:
  1151.  
  1152.      You can continue any RPG/free statement, except the /EXEC SQL and /TITLE 
  1153. directives and SQL statements between /EXEC SQL and /END-EXEC.  You can 
  1154. continue other directives and non-C-specs, as well as C-specs.  You cannot 
  1155. continue lines that follow the /DATA directive, lines between /FIX and /FREE 
  1156. directives, or lines in a file included with the /INCLUDEF directive.  (You 
  1157. can continue lines in a file included with the /INCLUDE directive.)  
  1158.  
  1159.      To continue a statement, use a plus (+) as the last nonblank, nontab 
  1160. character on a line.  For example: 
  1161.  
  1162.     XMOVE     'Name' +
  1163.          outfld
  1164.  
  1165.      When the RPG/free precompiler reads an input line that can be 
  1166. continued (i.e., it is not in an /INCLUDEF file, not between /FIX and 
  1167. /FREE directives, not an /EXEC SQL or /TITLE directive, and not a SQL 
  1168. statement between /EXEC SQL and /END-EXEC), the precompiler first checks 
  1169. for, and removes, a trailing + specifying a continued statement.  The 
  1170. precompiler than scans the line for an unquoted -- marking the beginning of a 
  1171. comment.  Any comment is removed from the input line and saved until 
  1172. the entire statement has been built.  
  1173.  
  1174.      The precompiler reads the next line and removes all leading blanks 
  1175. before the line is concatenated to the end of the continued line.  The 
  1176. precompiler repeats this process until the end of a statement (i.e., no 
  1177. continuation or end-of-input).
  1178.  
  1179.      If you specified /cmtline:same, the comments are concatenated into one 
  1180. long comment and output at the end of the statement (the exact position 
  1181. depends on the statement type).  If you specified /cmtline:prv, the 
  1182. comments are output one line per comment before the statement is translated.
  1183.  
  1184.      After building the statement and handling comments, the precompiler 
  1185. parses the input statement according to RPG/free syntax rules.
  1186.  
  1187.      If you need to end a line with  +  (e.g., in the replacement text of a 
  1188. macro), just code it like:
  1189.  
  1190.     /DEFINE  bump   1 + --Comment to allow  +  as last character
  1191.  
  1192. The trailing comment will be stripped, and the line will end with +.
  1193.  
  1194.  
  1195. XI.D. PROGRAM STRUCTURE:
  1196.  
  1197.      RPG/free programs have the same structure as standard RPG programs.  You 
  1198. specify the form type with a directive.  A complete program might contain:
  1199.  
  1200.     /AUTORPT
  1201.      Auto-report specifications
  1202.     /CONTROL or /HEADER (optional)
  1203.      Control specifications
  1204.     /FILE
  1205.      File specifications
  1206.     /EXTENSION or /EXT
  1207.      Extension specifications
  1208.     /LINE
  1209.      Line counter specifications
  1210.     /TELCOM
  1211.      Telecommunications specifications
  1212.     /INPUT
  1213.      Input specifications
  1214.     /CALC
  1215.      Calculation specifications
  1216.     /OUTPUT
  1217.      Output specifications
  1218.     /DATA
  1219.     **
  1220.      File translation records
  1221.     **
  1222.      Alternate collating sequence records
  1223.     **
  1224.      Compile-time array and table data
  1225.  
  1226.  
  1227.      The precompiler starts with form type as H, so a beginning /CONTROL is
  1228. optional.  You do not have to include directives for unused form types.
  1229. The form types must be in the standard RPG order, the precompiler does not
  1230. sort them.
  1231.  
  1232.  
  1233. XI.E. NON-C-SPEC STATEMENTS:
  1234.  
  1235.      H, F, E, L, T, I, O, and U specifications are output without 
  1236. translation, except for proper column alignment based on the /FIRSTCOL 
  1237. directive setting.
  1238.  
  1239.      With the default /FIRSTCOL setting (6), you begin each statement with 
  1240. the form character in position 1.  (This is redundant, but aids readability.)
  1241.  
  1242.      To eliminate form characters, use the /FIRSTCOL 7 directive.
  1243.  
  1244.      To add characters in positions 1-5, use /FIRSTCOL n where n is 1 to 5 
  1245. and specifies where position 1 of the input will be placed in the output.
  1246. You can use multiple /FIRSTCOL directives, so you can bracket a statement
  1247. that you want to mark and leave the others as the default:
  1248.  
  1249.     FAFILE1  ....
  1250.     /FIRSTCOL 4
  1251.     >>FAFILE2  ...
  1252.     /FIRSTCOL 6
  1253.     FAFILE3 ...
  1254.  
  1255.      Non-C-specs are not translated to uppercase, so you must code uppercase 
  1256. where the RPG compiler requires it.
  1257.  
  1258.  
  1259. XI.F. C-SPEC STATEMENTS:
  1260.  
  1261.      C-specs are free format, you can use blanks and tabs freely for 
  1262. alignment. You can also use upper or lower case for all keywords, 
  1263. identifiers, and special values.  Lower case is converted to upper case 
  1264. except within the sequence field (e.g., {v1.0} is unchanged), string 
  1265. constants (e.g., 'Name' is unchanged), and figurative constants 
  1266. (e.g., *all'x' becomes *ALL'x').
  1267.  
  1268.      A complete C-spec has the following parts:
  1269.  
  1270.     Sequence field
  1271.     Control level indicator
  1272.     Conditioning indicators
  1273.     Operation
  1274.     Declaration
  1275.     Half-adjust
  1276.     Resulting indicators
  1277.  
  1278.      Rules for combining these parts are the same as in standard RPG.
  1279.  
  1280.  
  1281. XI.G. MULTIPLE C-SPEC STATEMENTS:
  1282.  
  1283.      You can code multiple RPG/free C-specs on a single statement by 
  1284. separating the C-specs with a semicolon (;).  For example:
  1285.  
  1286.     tmp = a; a = b; b = tmp  -- Swap a and b
  1287.  
  1288.      Statements with multiple C-specs can be continued across input lines, 
  1289. which is valuable primarily for defining macros that have multiple C-specs.
  1290. For example:
  1291.  
  1292.     /DEFINE    chksql            +        
  1293.         if sqlcod <> 0;        +
  1294.             exsr sqlerr;    +
  1295.         endif
  1296.  
  1297. can be used to simplify checking SQL return codes, as follows:
  1298.  
  1299.     /EXEC SQL
  1300.       SELECT * FROM cust WHERE custid = :inpid
  1301.     /END-EXEC
  1302.      chksql
  1303.  
  1304.      You cannot code directives or any other non-C-spec statement on a 
  1305. multiple-C-spec statement.         
  1306.  
  1307.  
  1308. XI.H. SEQUENCE FIELD (1-5):
  1309.  
  1310.      You can specify up to five characters to output in the standard RPG 
  1311. sequence field.  Use curly braces to delimit the sequence field:
  1312.  
  1313.     {V3.2a}  will generate:    V3.2a     in positions 1-5.
  1314.  
  1315. Here are a couple more examples:
  1316.  
  1317.     {12345} a = b
  1318.     {  >>}    READE  custr
  1319.  
  1320.      You cannot use a right brace (}), a single quote ('), or double dashes 
  1321. (--) within the sequence field.  The sequence field is truncated to five 
  1322. characters.  Within the braces, all blanks are significant.  The 
  1323. sequence field can be continued across lines with a +, but that is not good 
  1324. programming practice. 
  1325.  
  1326.  
  1327. XI.I. CONTROL LEVEL INDICATOR (7-8):
  1328.  
  1329.      You can specify a control level indictor in two ways.  You can use any 
  1330. one of the following control level indicator keywords:
  1331.  
  1332.     L0()    L1()    L2()    L3()    L4()
  1333.     L5()    L6()    L7()    L8()    L9()    LR()
  1334.  
  1335.      You must use the parentheses.  The left parenthesis must immediately 
  1336. follow the keyword.  You can use blanks or tabs anywhere within the 
  1337. parentheses.
  1338.  
  1339.      Alternately, you can use a form like LEVEL(L0) to specify L0-L9 or LR.  
  1340. The indicator can be a standard level indicator (L0, ..., LR) or a symbolic 
  1341. indicator (*INL0, ..., *INLR).
  1342.  
  1343.  
  1344. XI.J. CONDITIONING INDICATORS (7-8 and 9-17):
  1345.  
  1346.      You can specify up to three conditioning indicators for each statement 
  1347. as:
  1348.  
  1349.     (01 02 03)     or    First or only conditioning indicators
  1350.     COND(01 02 03)        for statement
  1351.  
  1352.     AND(01 02 03)        AND'd indicators, puts AN in 7-8
  1353.  
  1354.     OR(01 02 03)        OR'd indicators, puts OR in 7-8
  1355.  
  1356.      You can specify negated indicators as (n01 n02 n03).
  1357.  
  1358.      You can use symbolic indicators as (*in01 *in02 *in03) or 
  1359.      (*inn01 *inn02 *inn03).
  1360.  
  1361.  
  1362. XI.K. OPERATION (18-48):
  1363.  
  1364.      The operation specifies what will be generated for the standard RPG 
  1365. opcode (positions 28-32), Factor1 (18-27), Factor2 (33-42), and 
  1366. Result (43-48).
  1367.  
  1368.      Allowable operands for Factor1, Factor2, and Result are:
  1369.  
  1370.       Operand type               Example         Fact1   Fact2   Result
  1371.       ------------------------------   -------         -----   -----   ------
  1372.       Identifier               custid           Y       Y       Y
  1373.       Subscripted identifier           ary,2           Y       Y       Y
  1374.       Non-negated symbolic indicator   *IN01           Y       Y       Y
  1375.       Subscripted indicator array      *IN,i           Y       Y       Y
  1376.       Null placeholder                *N           Y       Y       Y
  1377.       Special value               *zero           Y       Y       Y
  1378.       Numeric constant               -1.2           Y       Y       N
  1379.       String constant               'Name'           Y       Y       N
  1380.       String reference               str:strlen      Y       Y       N
  1381.       Figurative constant           *all'X'           Y       Y       N
  1382.       Hexadecimal constant           x'f0'           Y       Y       N
  1383.  
  1384.  
  1385.      Within operations, array references have the same form as in 
  1386. standard RPG, except you can use blanks around the comma.  For example:  
  1387.  
  1388.     ADD  X, I       Y, I                  or
  1389.     ADD  X , I      Y , I
  1390.  
  1391.      Release 3.0 of RPG/400 allows string references that have two parts 
  1392. seperated by a colon.  In RPG/free, you can use blanks around the colon.  For 
  1393. example:
  1394.  
  1395.     SUBSTR LEN( strlen )  SRCSTR( old_str : bgnpos )  TGTSTR( new_str )
  1396.  
  1397.  
  1398. XI.L. RPG/free OPERATIONS:
  1399.  
  1400.      There are two forms of RPG/free operation: arithmetic assignment and 
  1401. keyword operation.
  1402.  
  1403.  
  1404. XI.M. ARITHMETIC ASSIGNMENTS:
  1405.  
  1406.      Arithmetic assignments have the form:    a = b    or   a = b + c           
  1407.     
  1408.      You can use a single +, *, -, or / arithmetic operator.  
  1409.      
  1410.      You can't use parentheses or compound expressions such as 
  1411.      a = (b + c) * d.
  1412.  
  1413.  
  1414.  
  1415. XI.N. KEYWORD OPERATIONS:
  1416.  
  1417.      Standard keyword operations have an operation-operand form:
  1418.  
  1419.     operation  factor1  factor2  result
  1420.  
  1421.     If an operation has blank or optional Factor1 or Factor2, you usually do 
  1422. not have to specify it.  RPG/free looks up the operation and places operands
  1423. where they belong.  You can use the placeholder *n or *N to explicitly
  1424. place blanks in an operand field.  For example,
  1425.  
  1426.     DELETE cusrcd               generates           DELETCUSRCD
  1427.     DELETE *n cusrcd            generates           DELETCUSRCD
  1428.     DELETE custid  cusrcd       generates  CUSTID   DELETCUSRCD
  1429.     UPDATE cusfil               generates           UPDATCUSFIL
  1430.     UPDATE cusfil  cusds        generates           UPDATCUSFIL   CUSDS
  1431.  
  1432.      Note that RPG II and RPG III have different rules for the following 
  1433. opcodes: CHAIN, DEBUG, DEFN, POST, READ, READE, and READP.  RPG/free default 
  1434. placement will correctly handle all versions of CHAIN, READ, READE, and 
  1435. READP.  You can use either the /rpgii option or explicit *n placeholders for 
  1436. the RPG II versions of DEBUG, DEFN, and POST.
  1437.  
  1438.      RPG/400 (R3.0 and later) differs from RPG III in letting Factor1 be 
  1439. optional on READE and REDPE.  You can use either the /rpg400 option or 
  1440. explicitly code *n placeholders when you don't use Factor1.
  1441.  
  1442.  
  1443. XI.O. OPCODE SYNONYMS:
  1444.  
  1445.      You can use the following correctly spelled synonyms instead of standard 
  1446. RPG opcodes:
  1447.  
  1448.     RPG/free synonym    Standard RPG opcode
  1449.     ----------------    -------------------
  1450.     BITOFF            BITOF
  1451.     CATSTR            CAT    (RPG/400)
  1452.                 CATST    (Lattice)
  1453.     CASE            CAS
  1454.     COMMIT            COMIT
  1455.     DELETE            DELET
  1456.     DISPLAY            DSPLY
  1457.     ENDCASE            END
  1458.     ENDDO            END
  1459.     ENDFOR            END
  1460.     ENDIF            END
  1461.     ENDLOOP            END
  1462.     ENDSUBSTR        (second part of a Lattice SUBST operation)
  1463.     ENDUNTIL        END
  1464.     ENDWHILE        END
  1465.     EXITSR            EXITBLOCK (RPG/free extended operation)
  1466.     LOOKUP            LOKUP
  1467.     OCCUR            OCUR
  1468.     READPE            REDPE
  1469.     RETURN            RETRN
  1470.     ROLLBACK        ROLBK
  1471.     SETOFF            SETOF
  1472.     SUBSTR            SUBST
  1473.     UNLOCK            UNLCK
  1474.     UPDATE            UPDAT
  1475.     XCATSTR            XCAT     (RPG/free extended operation)
  1476.     XSUBSTR            XSUBST    (RPG/free extended operation)
  1477.  
  1478.  
  1479. XI.P. OPERAND KEYWORDS:
  1480.  
  1481.      If you think of C-spec operands as Factor1, Factor2, Result instead of
  1482. first, second, and third operands, you can use RPG/free operand keywords as 
  1483. in the examples below.  Operands can be in any order when you use keywords; 
  1484. and you can use blanks freely within the parentheses.
  1485.  
  1486.     UPDATE  F2( cusfil )  R( cusds )
  1487.     
  1488.     add  f1( x )   f2( y )  r(  z )
  1489.  
  1490.     add  r( z  )   f2( y )  f1( x )
  1491.  
  1492.  
  1493.      The following operations have synonyms for the F1, F2, and R keywords.  
  1494.  
  1495.  
  1496.             ------------- Keyword ------------------
  1497.     Opcode        F1        F2        R
  1498.     ------        ---------    ----------    --------
  1499.     ACQ          DEV        FILE        
  1500.     BITOF                SELECT        DATA
  1501.     BITON                SELECT        DATA
  1502.     CABxx        F1        F2        TAG
  1503.     CAS          F1        F2        SUBR
  1504.     CASE         F1        F2        SUBR
  1505.     CASxx        F1        F2        SUBR
  1506.     CHAIN        KEY        FILE or FMT    DS
  1507.     CLEAR        F1        DS        
  1508.     CLOSE                FILE        
  1509.     DEBUG        ID        FILE        DATA
  1510.     DEFN         TYPE        REFFLD or    FLD
  1511.                     DTAARA
  1512.     DELET        KEY        FILE or FMT        
  1513.     DO           FROM        TO        IDX
  1514.     DSPLY        MSG or MSGID    TO        REPLY
  1515.     END                  INC        
  1516.     ENDSR        TAG        CONTROL        
  1517.     ENDSS                STRLEN        TGTSTR
  1518.     EXFMT                FMT        
  1519.     FEOD                 FILE        
  1520.     FOR          FROM        TO        IDX
  1521.     FORCE                FILE        
  1522.     IN           LOCK        DTAARA        
  1523.     LOKUP        ARG        TABLE or    MATCHTBL
  1524.                     ARRAY
  1525.     NEXT         DEV        FILE        
  1526.     OCUR         SETIDX        DS        RESULTIDX
  1527.     OPEN                 FILE        
  1528.     OUT          LOCK        DTAARA        
  1529.     PARM         RTNVAL        INVAL        FLD
  1530.     POST         DEV        FILE        DS
  1531.     READ                 FILE or FMT    DS
  1532.     READC                FMT        
  1533.     READE        KEY        FILE or FMT    DS
  1534.     READP                FILE or FMT    DS
  1535.     REDPE        KEY        FILE or FMT    DS
  1536.     REL          DEV        FILE        R
  1537.     RESET        F1        DS        
  1538.     SCAN         COMP        BASE        POS
  1539.     SETGT        KEY        FILE or FMT        
  1540.     SETLL        KEY        FILE or FMT        
  1541.     SUBST        STRLEN        SRCSTR        TGTSTR    -- RPG/400
  1542.     SUBST        SRCSTR        BGNPOS            -- Lattice
  1543.     TESTB                SELECT        DATA
  1544.     UNLCK                DTAARA        
  1545.     UPDAT                FILE or FMT    DS
  1546.     WRITE                FILE or FMT    DS
  1547.     XSUBST       STRLEN        SRCSTR        TGTSTR
  1548.  
  1549.  
  1550.      These synonyms can make your code very readable.  You can mix F1, F2, 
  1551. and R with the synonyms, but you can only use the synonyms defined for each 
  1552. opcode.  For example, the following is valid:
  1553.  
  1554.     SUBST   R( x )   F2(   y : bgn )   STRLEN( strlen )
  1555.     
  1556. but
  1557.  
  1558.         SUBST   R( x )   FILE( y : bgn )   STRLEN( strlen )
  1559.     
  1560. is not.     
  1561.  
  1562.  
  1563.      You can mix the keyword and positional forms, but be careful because the
  1564. default placement of operands does not work the same as in S/38 and OS/400 
  1565. CL. RPG/free first places operands specified with keywords, then fills in 
  1566. vacant operands using its default rules.
  1567.  
  1568.  
  1569. XI.Q. EXTENDED CONTROL STRUCTURE OPERATIONS:
  1570.  
  1571.      RPG/free has a set of extended operations for control structures:
  1572.  
  1573.     RPG/free        Standard RPG
  1574.     ---------------------    ---------------------------------------
  1575.     AND    f1 =  f2        F1    ANDEQF2
  1576.     AND    f1        F1    ANDEQ'1'
  1577.  
  1578.     BREAK                GOTO    BRK#1#
  1579.  
  1580.     CASE   f1 <  f2 r    F1    CASLTF2        R
  1581.     CASE   f1  r        F1    CASEQ'1'    R
  1582.     CASE   r            CAS        R
  1583.  
  1584.     CONTINUE            GOTO    CNT#1#
  1585.  
  1586.     FOR    r = f1 f2    F1    DO   F2        R
  1587.     ENDFOR f2            END  F2
  1588.  
  1589.     EXITBLOCK            GOTO    EXT#1#
  1590.     EXITSR                GOTO    EXT#1#
  1591.  
  1592.     IF     f1 <= f2     F1    IFLE F2
  1593.     IF     f1        F1    IFEQ '1'
  1594.  
  1595.     LOOP            '1'    DOWEQ'1'
  1596.  
  1597.     OR     f1 >  f2        F1    ORGT F2
  1598.     OR     f1        F1    OREQ '1'
  1599.  
  1600.     UNTIL  f1 <> f2        F1    DOUNEF2
  1601.     UNTIL  f1        F1    DOUEQ'1'
  1602.  
  1603.     WHILE  f1 >= f2        F1    DOWGEF2
  1604.     WHILE  f1        F1    DOWEQ'1'
  1605.  
  1606.  
  1607.      The logical operators are:
  1608.  
  1609.     Operator    Meaning
  1610.     --------    --------------
  1611.        <        Less than
  1612.        <=        Less than or equal
  1613.        =        Equal
  1614.        <>        Not equal
  1615.        >=        Greater than or equal
  1616.        >        Greater than
  1617.  
  1618.  
  1619.      You can also use operand keywords with extended operations (although it 
  1620. isn't very readable):
  1621.  
  1622.     IF f1(x) op(<=) f2(y)
  1623.  
  1624.     FOR r(idx) op(=) f1(bgn) f2(end)
  1625.  
  1626.      The "noise" word TO is defined as a macro with blank replacement text, 
  1627. so you can code:
  1628.  
  1629.     FOR i = 1 TO n
  1630.  
  1631. for readability.
  1632.  
  1633.      There are four built-in macros that you can use with control
  1634. structures:
  1635.  
  1636.     Macro name    Replacement text
  1637.     ----------    ----------------
  1638.     *AND        ;AND
  1639.     *OR        ;OR
  1640.     *NOT        IF *TRUE <>
  1641.     ELSEIF        ELSE; IF
  1642.  
  1643. The *AND and *OR operators let you use unparenthesized logical expressions:
  1644.  
  1645.     IF a = b *AND c = d
  1646.  
  1647. Note that because *AND and *OR just generate a series of standard RPG
  1648. ANDxx and ORxx operations, you cannot use parenthesized logical expressions.
  1649.  
  1650. The *NOT operator can be used with "logical" variables:
  1651.  
  1652.     IF *NOT end_of_file
  1653.  
  1654. You cannot use *NOT to negate a logical expression.
  1655.  
  1656.      The ELSEIF macro lets you code "else if" logical constructs in a
  1657. slightly more compact and readable fashion:
  1658.  
  1659.     IF     a = b
  1660.            ....
  1661.     ELSEIF a = c
  1662.            ....
  1663.     ELSE;  ....
  1664.     ENDIF; ENDIF
  1665.  
  1666. Note that you must still code one ENDIF to match the IF, and one ENDIF
  1667. to match each ELSEIF.
  1668.  
  1669.  
  1670.      The BREAK, CONTINUE, EXITBLOCK, and EXITSR labels are generated by 
  1671. RPG/free to match TAG labels that are generated at the end of a loop, main 
  1672. block, or subroutine.
  1673.  
  1674.      You can code loops as follows:
  1675.  
  1676.          /DEFINE eof_cust *IN90
  1677.  
  1678.     LOOP
  1679.       READ  FMT( custr )  EOF( eof_cust )      
  1680.       IF eof_cust
  1681.          BREAK
  1682.       ENDIF
  1683.       -- Process a customer
  1684.       ...
  1685.     ENDLOOP
  1686.  
  1687.      The LOOP operation is a never-ending loop; you should use BREAK or 
  1688. EXITBLOCK to exit the loop.  
  1689.  
  1690.      The BREAK operation exits the innermost loop.  
  1691.      
  1692.      The CONTINUE operation skips the rest if the innermost loop 
  1693. and immediately branches to the loop's test condition.  Another iteration 
  1694. will execute, if-and-only-if the loop condition is still true.  
  1695.  
  1696.      The EXITBLOCK operation exits the current subroutine, or the main block 
  1697. that precedes the first subroutine.
  1698.  
  1699.  
  1700. XI.R. EXTENDED CHARACTER ASSIGNMENT OPERATIONS:
  1701.  
  1702.      RPG/free provides "safe" assignment operations for character variables.  
  1703. These operations blank fill the Result before executing the operation, so you 
  1704. don't get garbage left in the result.
  1705.  
  1706.     RPG/free        Standard RPG
  1707.     ---------------------    ---------------------------------------
  1708.     XCAT    f1  f2  r           MOVE *BLANK     R
  1709.                 F1     CAT  F2         R
  1710.  
  1711.     XCATST  f1  f2  r           MOVE *BLANK     R
  1712.                 F1     CATSTF2         R
  1713.  
  1714.     XMOVE       f2  r           MOVE *BLANK     R
  1715.                        MOVELF2         R
  1716.  
  1717.     XSUBST    f1  f2  r           MOVE *BLANK     R
  1718.                 F1     SUBSTF2         R
  1719.  
  1720.      You should not use the extended string operations with the same 
  1721. operand used for both the Result and either Factor1 or Factor2 because
  1722. blanks will be moved to the Factor1 or Factor2 before the string
  1723. operation.  (RPG/free will emit a warning if you do.)
  1724. As an example, do NOT code:
  1725.   
  1726.     XCAT  r  f2  r
  1727.  
  1728. Instead, if you want to append f2 to r, code: 
  1729.  
  1730.     CAT   r  f2:0  r
  1731.  
  1732. Note that you must code the number of blanks to be inserted (the :0)
  1733. or else you will simple move r to r.  (RPG/400 provides no mechanism
  1734. to build real, variable length strings.)
  1735.  
  1736.     
  1737. XI.S. DECLARATIONS (49-52):
  1738.  
  1739.      After an operation and its operands, you can declare the Result field:
  1740.  
  1741.     ADD x y z LEN(7 0)        Declares numeric field Z
  1742.     
  1743.     a = b * c LEN(7 2)        Declares numeric field A
  1744.  
  1745.     MOVE 'Name' outfld LEN(8)    Declares character field OUTFLD
  1746.  
  1747.      You can use relative sizes on the DEFN operation:
  1748.  
  1749.     DEFN *LIKE x z LEN(+2)        Declares numeric field Z as 2
  1750.                     positions larger than X.
  1751.  
  1752.  
  1753. XI.T. DCL OPERATION:
  1754.  
  1755.      The RPG/free DCL extended operation allows independent field 
  1756. declarations.
  1757.  
  1758.     RPG/free operation    Standard RPG
  1759.     ------------------    ---------------------------
  1760.     DCL r LEN(5)        MOVELR        R      5
  1761.  
  1762.     DCL r LEN(5 0)        Z-ADDR        R      50
  1763.  
  1764.     DCL f2 r LEN(5)        MOVE *BLANK    R      5
  1765.                 MOVELF2        R
  1766.  
  1767.     DCL f2 r LEN(5 0)    Z-ADDF2        r      50
  1768.  
  1769.      Note that the DCL generates executable statements.  You may want to put 
  1770. these in an initialization subroutine that is executed only once (in R3.0 of 
  1771. RPG/400, you can use the *INZSR subroutine).  Or, you can put DCL 
  1772. statements under a conditional statement:
  1773.  
  1774.     IF pgminz = *FALSE
  1775.  
  1776.        DCL inpcid LEN(5 0)
  1777.        ...
  1778.        MOVE *TRUE TO pgminz
  1779.  
  1780.     ENDIF
  1781.  
  1782.  
  1783. XI.U. HALF-ADJUST (53):
  1784.  
  1785.      On arithmetic operations, you can code H() to specify half-adjust.
  1786.  
  1787.  
  1788. XI.V. RESULTING INDICATORS (54-59):
  1789.  
  1790.      You can specify up to three resulting indicators in two ways: as a list
  1791. enclosed within RESULT(...) or with individual resulting indicator keywords.
  1792.  
  1793.      The three relative positions within a RESULT(...) list correspond to 
  1794. positions 54-55, 56-57, and 58-59.  For example:
  1795.  
  1796.                             555555
  1797.     RPG/free                    456789
  1798.     ----------------                ------
  1799.     RESULT(01 *n 02)          generates    01  02
  1800.  
  1801.      You can use symbolic indicators, as in RESULT(*in01 *in02).  You cannot 
  1802. use negated indicators (e.g., N01).
  1803.  
  1804.      Instead of a RESULT(...) list, you can use the following keywords:
  1805.  
  1806.     54-55        56-57        58-59        Notes
  1807.     ----------    ----------    ----------    -----------
  1808.     RI1        RI2        RI3        e.g., SETON
  1809.     POS        NEG        ZER        e.g., ADD
  1810.                     ZERO
  1811.                     ZERBLK        e.g., MOVE
  1812.                     BLANK
  1813.                     BLK
  1814.     HI        LO        EQ        e.g., LOKUP
  1815.     NR        ER        EOF        e.g., CHAIN, READ
  1816.             ERR        BOF        e.g., READP
  1817.     OFF        MIX        ON        TESTB
  1818.     ALLNUM        LEADBLK        ALLBLK        TESTN
  1819.     ZONEA        ZONEJ        ZONEX        TESTZ
  1820.     SHTDN                        SHTDN
  1821.                     FOUND        SCAN
  1822.                     FND        SCAN
  1823.  
  1824.      You don't have to use the matching keywords for each operation.  
  1825. For example, you can use:
  1826.  
  1827.     MOVE x  y  HI(01) LO(02) EQ(03)
  1828.  
  1829.      You can place resulting indicator keywords in any order, but you cannot 
  1830. specify the same standard RPG positions more than once.  You can use symbolic 
  1831. indicators, but not negated indicators.  You cannot use *n with resulting 
  1832. indicator keywords other than RESULT.
  1833.  
  1834.  
  1835.             XII. STANDARD RPG DIRECTIVES
  1836.             ----------------------------
  1837.  
  1838.      RPG/free supports the following standard RPG compiler directives:
  1839.  
  1840.     /COPY    host-file-member-spec
  1841.  
  1842.     /EJECT
  1843.  
  1844.     /EXEC SQL   sql-statement
  1845.       sql-statement
  1846.       ...
  1847.     /END-EXEC
  1848.  
  1849.     /PRINT  GEN
  1850.     /PRINT  NOGEN
  1851.  
  1852.     /SKIP   n
  1853.  
  1854.     /SPACE  n
  1855.  
  1856.     /TITLE  title
  1857.  
  1858.      You can use blanks and tabs between a directive keyword and its 
  1859. argument, the precompiler realigns the argument to meet standard RPG 
  1860. requirements. 
  1861.  
  1862.      SQL statements between the /EXEC SQL and /END-EXEC directives must not 
  1863. have the leading  +  used in standard RPG/400; the  +  is added by the 
  1864. precompiler.
  1865.  
  1866.  
  1867.             XIII. RPG/free DIRECTIVES                
  1868.             -------------------------
  1869.  
  1870.      RPG/free includes the following precompiler directives:
  1871.  
  1872.     /DEFINE   identifier  replacement-text         Define a macro
  1873.  
  1874.     /UNDEFINE identifier                 Remove macro definition
  1875.  
  1876.     /DUMPMAC                     Output macro table to
  1877.                              file dump.rpf
  1878.  
  1879.     /FIRSTCOL  n                     Set output position
  1880.                              for non-C-specs
  1881.  
  1882.     /FIX                         Begin fixed-format input
  1883.  
  1884.     /FREE                         Resume free-format input
  1885.  
  1886.     /IF DEFINED( macro )                 Conditionally translate
  1887.     /IF NOT DEFINED( macro )             statements
  1888.     /ELSEIF DEFINED( macro )
  1889.     /ELSEIF NOT DEFINED( macro )
  1890.     /ELSE
  1891.     /ENDIF
  1892.  
  1893.     /INCLUDE  pc-file-spec                 Include free-format 
  1894.                              file
  1895.  
  1896.     /INCLUDEF pc-file-spec                 Include fixed-format 
  1897.                              file
  1898.  
  1899.  
  1900. XIII.A. SETTING FIRST COLUMN (/FIRSTCOL):
  1901.  
  1902.      The /FIRSTCOL directive has an argument from 1 to 7 that specifies the
  1903. position in the standard RPG output where the first position in a non-C-spec
  1904. input line will be placed.  The default is 6 which requires you to begin
  1905. non-C-specs with the proper form type character.
  1906.  
  1907. /FIRSTCOL does not effect lines between /FIX and /FREE directives, within
  1908. an /INCLUDEF file, or following the /DATA directive.
  1909.  
  1910.  
  1911. XIII.B. SOURCE MACROS (/DEFINE, /UNDEFINE, and /DUMPMAC):
  1912.  
  1913.      An RPG/free source macro is an identifier for a string of 
  1914. replacement text. Source macros are only supported for C-specs, the 
  1915. precompiler will not translate macros in other types of statements.
  1916.  
  1917.      Although RPG/free macros are fairly simple, they provide great 
  1918. flexibility in creating highly readable programs.  To define a macro, code 
  1919. /DEFINE followed by one or more blanks and tabs and the macro name.  Follow 
  1920. the macro name with one or more blanks or tabs and then code the replacement 
  1921. text.  The replacement text begins with the first nonblank, nontab after the 
  1922. macro name and ends with the last nonblank, nontab character on the same 
  1923. statement.
  1924.  
  1925.      The macro name must begin with a letter, national character ($, #, @), 
  1926. or the underscore (_) readability character; and can include letters, 
  1927. national characters, numbers, and underscore.  Upper and lower case letters 
  1928. are considered identical in matching macro names.  A macro name can be up to 
  1929. 30 characters long.
  1930.  
  1931.      The replacement text can include any characters, except leading or 
  1932. trailing blanks and tabs, which are always trimmed; and double dashes (--), 
  1933. which begin a comment.  If you want to end a macro's replacement text with a 
  1934. plus (+), code a comment after the + so it will not be handled as a 
  1935. continuation.  For example: 
  1936.  
  1937.     /DEFINE  bump   1 + --Comment to allow  +  as last character
  1938.  
  1939.      As the precompiler encounters tokens during its parse of an RPG/free 
  1940. C-spec, it replaces every occurrence of a macro identifier with the 
  1941. corresponding replacement text.  The precompiler then restarts its parse at 
  1942. the beginning of the replacement text, thus allowing nested macros.  For 
  1943. example:
  1944.  
  1945.     /DEFINE    customer_id    csid
  1946.     /DEFINE exit_key    *in03
  1947.     /DEFINE IFNOT        IF *TRUE <>
  1948.  
  1949.     IFNOT    exit_key        becomes           IF '1' <> *in03
  1950.  
  1951.      The precompiler does not replace a macro in any input line until after 
  1952. it encounters the macro's definition on a /DEFINE.  
  1953.  
  1954.      If you code a /DEFINE with a macro name and replacement text that 
  1955. is nothing but blanks and tabs, the precompiler replaces the macro name with 
  1956. the null string (i.e., deletes it) when the macro is encountered in 
  1957. subsequent input lines.  The RPG/free precompiler automatically defines TO as 
  1958. blanks when it starts (you can /UNDEFINE TO, if you don't want it replaced 
  1959. with blank).  You can use blank "noise" word macros to add readability words 
  1960. to your statements:
  1961.  
  1962.     /DEFINE     FROM
  1963.  
  1964.     ADD x TO y            becomes        ADD x y
  1965.  
  1966.     SUB x FROM y            becomes        SUB x y
  1967.  
  1968.      Be careful not to code recursive macros, which will cause a syntax 
  1969. error:
  1970.  
  1971.     /DEFINE x y
  1972.     /DEFINE y x
  1973.  
  1974.     a = x  causes syntax error
  1975.  
  1976.      To remove a macro definition, use /UNDEFINE with the macro name:
  1977.  
  1978.     /DEFINE x csid
  1979.  
  1980.     a = x                becomes        a = csid
  1981.  
  1982.     /UNDEFINE x
  1983.  
  1984.     a = x                remains        a = x
  1985.  
  1986.  
  1987.      If you try to /DEFINE a macro that is already defined, you get an 
  1988. error.  (This prevents accidental redefinitions.)  To redefine a macro, 
  1989. you must first use /UNDEFINE to remove it from the definitions, and then 
  1990. use /DEFINE for the new definition.  You can use /IF DEFINED(macro), 
  1991. discussed below, to conditionally define (or redefine) macros.    For example:
  1992.  
  1993.     /DEFINE      customer_id  csid
  1994.  
  1995.     MOVE customer_id  outfld    becomes       MOVE csid outfld
  1996.  
  1997.     /UNDEFINE customer_id
  1998.     /DEFINE   customer_id  custid
  1999.  
  2000.     MOVE customer_id  outfld    becomes       MOVE custid outfld
  2001.  
  2002.      To prevent accidentally defining two macros as the same standard RPG
  2003. field, you can use the built-in macro function %SYSSYMBOL.  For example,
  2004. if you coded the following:
  2005.  
  2006.     /DEFINE cust_id    CID
  2007.     ...
  2008.     /DEFINE charge_ID  CID
  2009.  
  2010. the generated RPG program might not work correctly because CID is used for
  2011. two different purposes.  To prevent duplicate use of the same symbol as
  2012. replacement text, code:
  2013.  
  2014.     /DEFINE cust_id     %SYSSYMBOL( CID )
  2015.  
  2016. This definition checks all existing macros to be sure none uses CID as
  2017. the replacement text.  All subsequent macros, whether they use %SYSSYMBOL
  2018. or not, are prevented from using CID as the replacement text.  The
  2019. argument to %SYSSYMBOL is a single string with no embedded blanks, tabs,
  2020. or parantheses.  You must use %SYSSYMBOL by itself, not as part of a
  2021. longer replacement string.  (You can use nested macros, if you want to
  2022. use the symbol in a longer string.)
  2023.  
  2024.      You can let RPG/free generate standard RPG names, if you don't need
  2025. to work directly with the generated RPG code:
  2026.  
  2027.     /DEFINE cust_id     %SYSSYMBOL( *GEN )
  2028.  
  2029. This is equivalent to a macro definition like:
  2030.  
  2031.     /DEFINE cust_id     %SYSSYMBOL( SYS#1# )
  2032.  
  2033. Each time *GEN is referenced, the RPG/free precompiler generates a new
  2034. six-character name similar to SYS#n# (or SYSnn#, SYnnn#, Snnnn#).  Then
  2035. %SYSSYMBOL makes sure this name is not used as replacement text in any
  2036. other macro.  %SYSSYMBOL( *GEN ) can greatly simplify using long
  2037. variable names in RPG/free.
  2038.  
  2039.      You can achieve the effect of limiting the scope of macro names to
  2040. a single source file (i.e., a file that you /INCLUDE) by the defining
  2041. the macros at the beginning of the source file, using %SYSSYMBOL, and
  2042. undefining them at the end of the source file:
  2043.  
  2044.     -- Beginning of myfile.rpi
  2045.  
  2046.     /DEFINE   local_var  %SYSSYMBOL( *GEN )
  2047.     .... code
  2048.     /UNDEFINE local_var
  2049.  
  2050.     -- end of myfile.rpi
  2051.  
  2052. With this technique, local_var can be used in several source files
  2053. without conflicts.  The %SYSSYMBOL( *GEN ) uses a different RPG
  2054. field name for each source file, so there is no accidental conflicting
  2055. use of the same RPG variable.  The /UNDEFINE lets the macro name 
  2056. local_var be /DEFINE'd in multiple places.
  2057.  
  2058.  
  2059.      The /DUMPMAC directive will write the table of current macro definitions 
  2060. to the file dump.rpf.  A header line provides the input line number when 
  2061. the table was dumped.  Each macro is output as:
  2062.  
  2063.     [macroname] [replacement text] [x]
  2064.  
  2065. where x is 'S' if the macro is defined as a %SYSSYMBOL, and blank otherwise.
  2066. You can use /DUMPMAC to trace macro definitions if you are having problems 
  2067. in your program.  When RPG/free encounters the first /DUMPMAC directive, 
  2068. it clears dump.rpf before writing out the table.  When it encounters 
  2069. subsequent /DUMPMAC directives, it appends the current table to the file.
  2070.  
  2071.  
  2072. XIII.C. PREDEFINED LANGUAGE, COMPILER, and LOGICAL CONSTANT MACROS
  2073.  
  2074.      When RPG/free starts, it defines macros for the version of RPG/free and
  2075. the target RPG language and compiler that were specified (or defaulted) for 
  2076. the translation.  You can test these with /IF DEFINED (see below) to direct 
  2077. the translation based on RPG/free version or the target compiler.
  2078.  
  2079.      The PC version of RPG/free defines the following macros:
  2080.      
  2081.     Macros defined        Replacement text
  2082.     --------------------    -----------------------
  2083.     _RPGFREE_VER_PC_    'PC2.02'
  2084.     _RPGFREE_VER_SYS_    'PC'
  2085.     _RPGFREE_VER_NBR_    2.02
  2086.  
  2087. You can test _RPGFREE_VER_PC_ (and the other macros defined by the
  2088. other versions of RPG/free) to handle the proper file specification
  2089. syntax on /INCLUDE directives:
  2090.  
  2091.     /IF    DEFINED( _RPGFREE_VER_PC_ )
  2092.         /INCLUDE stdhdr.rpi
  2093.     /ELSEIF    DEFINED( _RPGFREE_VER_AS400_ )
  2094.         /INCLUDE rpisrc(stdhdr)
  2095.     /ENDIF
  2096.  
  2097.     You can also use these three macros in RPG/free C-specs to
  2098. either conditionally control execution (not precompilation) or to
  2099. display the version of the precompiler used.  For example:
  2100.  
  2101.     /DEFINE output_field OUTFLD
  2102.  
  2103.     XMOVE _RPGFREE_VER_PC TO output_field
  2104.  
  2105. will generate:
  2106.  
  2107.     MOVE *BLANK    OUTFLD
  2108.     MOVEL'PC2.02'  OUTFLD
  2109.  
  2110.  
  2111.  
  2112.  
  2113.      The compiler options define the following macros:
  2114.  
  2115.     Option        Macros defined        Replacement text
  2116.     --------------    --------------------    -----------------------
  2117.     /asna        _ASNA_            ASNA
  2118.             _RPG400_        RPG400
  2119.  
  2120.     /bps        _BPS_            BPS
  2121.             _RPGII_            RPGII
  2122.  
  2123.     /cspi        _CSPI_            CSPI
  2124.             _RPGII_            RPGII
  2125.  
  2126.     /cspi400    _CSPI400_        CSPI400
  2127.             _RPG400_        RPG400
  2128.  
  2129.     /lattice    _LATTICE_        LATTICE
  2130.             _RPGII_            RPGII
  2131.  
  2132.     /native        _NATIVE_        NATIVE
  2133.             _RPG400_        RPG400
  2134.  
  2135.     /rpgii        _IBMII_            IBMII
  2136.             _RPGII_            RPGII
  2137.  
  2138.     /rpgiii        _IBMIII_        IBMIII
  2139.             _RPGIII_        RPGIII
  2140.  
  2141.     /rpg400        _IBM400_        IBM400
  2142.             _RPG400_        RPG400
  2143.  
  2144.     /softwest    _SOFTWEST_        SOFTWEST
  2145.             _RPGII_            RPGII
  2146.  
  2147.     /trident    _TRIDENT_         TRIDENT
  2148.             _RPGIII_        RPGIII
  2149.  
  2150. You can use /IF DEFINED(...) to control precompilation based on the
  2151. target language.  For example:
  2152.  
  2153.     /IF DEFINED( _IBM400_ )
  2154.         XCATSTR  a  b  c
  2155.     /ELSE
  2156.         CALL 'CATSTR'
  2157.         PARM a
  2158.         PARM alen
  2159.         PARM b
  2160.         PARM blen
  2161.         PARM c
  2162.         PARM clen
  2163.     /ENDIF
  2164.  
  2165. This facility lets you maintain a single source code file for multiple
  2166. target compilers.
  2167.  
  2168.  
  2169.      RPG/free also installs the following macros based on the target RPG
  2170. compiler:
  2171.  
  2172.     _RPGFREE_LANGUAGE_  as 'RPGII', 'RPGIII', or 'RPG400'
  2173.  
  2174.     _RPGFREE_COMPILER_  as 'ASNA', 'BPS', 'CSPI', etc.
  2175.  
  2176. You can use _RPGFREE_LANGUAGE_ and _RPGFREE_COMPILER_ macros in RPG/free
  2177. C-specs, if you want to test or output the target language or compiler.
  2178.  
  2179.  
  2180.      RPG/free also automatically defines the macros:
  2181.  
  2182.          *TRUE    '1'
  2183.     *FALSE    '0'
  2184.     *AND    ;AND
  2185.     *OR    ;OR
  2186.     *NOT    IF *TRUE <>
  2187.     ELSEIF    ELSE; IF
  2188.     TO    <blank>
  2189.  
  2190.      You cannot /UNDEFINE or redefine *TRUE, *FALSE, *AND, *OR, and *NOT; 
  2191. they have been established as the RPG/free standard for logical (Boolean) 
  2192. values.  You can use these in C-specs, as in the following example:
  2193.  
  2194.     /DEFINE  LGL        LEN( 1 )
  2195.     /DEFINE  valid_order     vldord
  2196.  
  2197.     DCL valid_order LGL 
  2198.  
  2199.     MOVE *TRUE TO valid_order
  2200.  
  2201.  
  2202. XIII.D. DOS COMMAND LINE MACRO DEFINITION (/DEFINE:XXX OPTION)
  2203.  
  2204.      You can also use the /define:xxx option to define one macro from the 
  2205. DOS command line.  For example, you can enter:
  2206.  
  2207.     rf /define:test inp.rpf out.rpg
  2208.  
  2209. and the macro TEST will be defined with replacement text @TEST.  You can then 
  2210. use /IF DEFINED(TEST) to conditionally translate statements in the input 
  2211. file.  This allows you to control code generation without modifying the 
  2212. source.
  2213.  
  2214.  
  2215. XIII.E. CONDITIONAL CODE GENERATION (/IF, /ELSEIF, /ELSE, and /ENDIF):
  2216.  
  2217.      A set of conditional directives lets you test whether or not a macro 
  2218. is defined, and either translate a group of statements, or throw them into 
  2219. the "bit bucket".
  2220.  
  2221.      The /IF and /ELSEIF directives must have a condition like:
  2222.      
  2223.     /IF DEFINED( chksql )
  2224.  
  2225.     /IF NOT DEFINED( chksql )
  2226.     
  2227.     /ELSEIF DEFINED( chksql )
  2228.       
  2229.      The only condition you can test is whether or not a macro is defined.  
  2230. The DEFINED condition is true if-and-only-if the macro is currently defined.  
  2231. It doesn't matter what the replacement text is; even a macro with null 
  2232. replacement text is considered defined.
  2233.  
  2234.      If an /IF condition is true, the statements between the /IF and 
  2235. it's matching /ELSEIF, /ELSE, or /ENDIF are translated; otherwise these 
  2236. statements are skipped.  
  2237.  
  2238.      The statements between an /ELSE and it's matching /ENDIF are translated 
  2239. if no previous matching /IF or /ELSEIF condition was true.
  2240.  
  2241.      An /ELSEIF condition is treated as an /IF, if no previous matching /IF 
  2242. or /ELSEIF condition was true; otherwise, it's treated as an /ELSE.
  2243.  
  2244.      The normal rules of conditional statements apply to combining and 
  2245. nesting /IF, /ELSEIF, /ELSE, and, /ENDIF.
  2246.  
  2247.      Conditional directives control translation of all statement types, 
  2248. including non-C-specs, data, and directives such as /DEFINE, /FIX, /FIRSTCOL, 
  2249. /INCLUDE, and /INCLUDEF, and /EXEC SQL.
  2250.  
  2251.      You can use /IF to make sure you don't try to redefine commonly used 
  2252. macros.  The following example shows how you could define a small set of 
  2253. macros for common data types:
  2254.  
  2255.     /IF NOT DEFINED( _TYPE_MACS )
  2256.  
  2257.         /DEFINE _TYPE_MACS
  2258.  
  2259.         /DEFINE LGL    LEN( 1 )
  2260.         /DEFINE    INT    LEN( 7 0 )
  2261.         /DEFINE    DOLLAR    LEN( 9 2 )
  2262.         
  2263.     /ENDIF
  2264.     
  2265.      If these statements are put in an /INCLUDE file (see below), you can 
  2266. safely /INCLUDE the file in multiple places without worrying about an illegal 
  2267. duplicate definition of the type macros.  I recommend you follow the 
  2268. convention of beginning each "flag" macro, such as _TYPE_MACS in this 
  2269. example, with an underscore.  Using a standard notation for "flag" macro 
  2270. names helps avoid collisions with regular macro names.
  2271.  
  2272.      You can use conditional directives anywhere except between /FIX and 
  2273. /FREE directives or within an /INCLUDEF file (the precompiler will not "see" 
  2274. any other directives between /FIX and /FREE or within an /INCLUDEF file).  
  2275. You can use conditional directives within a /INCLUDE file (in fact, that's 
  2276. one of the most common places you'll use them).
  2277.  
  2278.      You can also use conditional directives following a /DATA directive.  
  2279. The /IF and other directives will not be output in the data, so you have a 
  2280. convenient way to conditionally generate array and table contents, as well as 
  2281. executable code.          
  2282.  
  2283.  
  2284. XIII.F. FIXED FORMAT INPUT (/FIX and /FREE):
  2285.  
  2286.      You can included standard, fixed-format RPG in an RPG/free source file 
  2287. by placing it after a /FIX directive.  All records following a /FIX directive
  2288. are moved without any modification to the output.  Fixed format lines end
  2289. when a /FREE directive or end-of-file is encountered.  If end-of-file is 
  2290. encountered while a /FIX is in effect, RPG/free will generate a commented 
  2291. /FREE to mark the end of the fix-format output.  You cannot span multiple 
  2292. input files with a /FIX; you must code a /FIX at the beginning of each one.  
  2293. (This approach prevents "runaway" /FIX directives.)
  2294.  
  2295.  
  2296. XIII.G. INCLUDING SOURCE FILES (/INCLUDE and /INCLUDEF):
  2297.  
  2298.      You can include RPG/free source at any point in the input by coding an 
  2299. /INCLUDE directive with a PC file specification:
  2300.  
  2301.     /INCLUDE  include1.rpf
  2302.  
  2303.      You can nest /INCLUDEs up to 20 deep (or the current DOS limit on open 
  2304. files), but you cannot use recursive /INCLUDEs.
  2305.  
  2306.      With /INCLUDE, all input is treated as RPG/free code (unless the 
  2307. included file contains a /FIX or /DATA directive).
  2308.  
  2309.      To include standard, fixed-format RPG, use /INCLUDEF.  All input lines 
  2310. from a file specified on an /INCLUDEF are treated the same as if they 
  2311. followed a /FIX directive.  The RPG/free precompiler does not recognize any 
  2312. directives within a file included using /INCLUDEF.
  2313.  
  2314.      RPG/free will generate a commented /ENDINCLUDE or /ENDINCLUDEF at the 
  2315. end of included statements, unless the /ENDINCLUDE or /ENDINCLUDEF would
  2316. occur in data (i.e., following a /DATA directive).
  2317.  
  2318.  
  2319. XIII.H. COMBINING MACROS AND INCLUDE FILES:
  2320.  
  2321.      A powerful technique is to use /INCLUDEs to "reuse" standard macros.  
  2322. Consider the following file as typmac.rpm:
  2323.  
  2324.     /IF NOT DEFINED( _TYPE_MACS )
  2325.  
  2326.         /DEFINE _TYPE_MACS
  2327.  
  2328.         /DEFINE LGL    LEN( 1 )
  2329.         /DEFINE    INT    LEN( 7 0 )
  2330.         /DEFINE    DOLLAR    LEN( 9 2 )
  2331.         
  2332.     /ENDIF
  2333.     
  2334.      Then in any RPG/free program, you can simply code:
  2335.  
  2336.     /INCLUDE typmac.rpm
  2337.  
  2338. to get the standard type definitions.  You can create /INCLUDE files for 
  2339. indicator definitions, standard variable declarations, etc.  
  2340.  
  2341.      Another technique is to define standard long names for database file 
  2342. fields. Consider the following file as custffd.rpm:
  2343.  
  2344.     -- Customer (CUSMST) file field descriptions
  2345.  
  2346.     /IF NOT DEFINED( _Cust_FFD_Dfn )
  2347.  
  2348.         /DEFINE _Cust_FFD_Dfn
  2349.  
  2350.         /DEFINE    Cust_ID        csid
  2351.         /DEFINE    Cust_name    csnam
  2352.         /DEFINE    Cust_discount    csdsc
  2353.         ...
  2354.     /ENDIF
  2355.  
  2356.      In any program that references the CUSMST file, you can simply code:
  2357.  
  2358.     /INCLUDE custffd.rpm
  2359.  
  2360. to make available the standard long names.  On the S/38 and AS/400, you can
  2361. automatically generate files like custffd.rpm by using the DSPFFD (Display
  2362. File Field Description) command.  The command CRTRPFFD (Create RPG/free 
  2363. Field Descriptions) automates this process, and is available for downloading 
  2364. from the NEWSLINK BBS.
  2365.  
  2366.  
  2367.             XIV. THE FUTURE OF RPG/free
  2368.             ---------------------------
  2369.  
  2370.      I'm working on the following features for RPG/free:
  2371.  
  2372.      * Full arithmetic expressions: a = ( b + c ) * d
  2373.  
  2374.      * Full logical expressions:    IF ( a <> b ) & ( ( c = d ) | ( c = e ) )
  2375.  
  2376.      * String expressions:          s = r || t
  2377.  
  2378.      * Free-format H-, ..., O-specs using OS/400 CL style syntax.
  2379.  
  2380.      * Substitution parameters in macro definitions.
  2381.  
  2382.      * Built in string and evaluation functions in macros and conditional
  2383.        directives.
  2384.  
  2385.      * Faster translation algorithms and dynamic storage management for 
  2386.        better performance.
  2387.  
  2388.  
  2389.      If you have suggestions, please let me know.
  2390.  
  2391.      Good luck to all "/free spirit" programmers!!!
  2392.  
  2393.  
  2394.  
  2395.             -- End of RFREE.DOC --        
  2396.             ----------------------